From 371fc467f471d0287ccb5135a98c69a24c3a0ced Mon Sep 17 00:00:00 2001 From: Chang-Hung Liang Date: Thu, 21 Mar 2024 16:55:56 +0800 Subject: [PATCH] docs(cli): document `primary` in `outputFields` --- docs/index.html | 34 +++++++++++++++++++++++++++++++++- packages/cli/README-source.md | 30 ++++++++++++++++++++++++++---- packages/cli/README.md | 30 ++++++++++++++++++++++++++---- packages/cli/docs/index.html | 34 +++++++++++++++++++++++++++++++++- 4 files changed, 118 insertions(+), 10 deletions(-) diff --git a/docs/index.html b/docs/index.html index 9ebc84693..c1694ad11 100644 --- a/docs/index.html +++ b/docs/index.html @@ -2747,11 +2747,13 @@

Output Fields

On each trigger, search, or create in the operation directive - you can provide an array of objects as fields under the outputFields. Output Fields are what users see when they select a field provided by your trigger, search or create to map it to another.

Output Fields are optional, but can be used to:

The schema for outputFields is shared with inputFields but only the key, label, type, and required properties are relevant:

Custom/Dynamic Output Fields are defined in the same way as Custom/Dynamic Input Fields.

@@ -5608,7 +5610,7 @@

How does deduplication work?

-

Each time a polling Zap runs, Zapier needs to decide which of the items in the response should trigger the zap. To do this, we compare the ids to all those we've seen before, trigger on new objects, and update the list of seen ids. When a Zap is turned on, we initialize the list of seen ids with a single poll. When it's turned off, we clear that list. For this reason, it's important that calls to a polling endpoint always return the newest items.

For example, the initial poll returns objects 4, 5, and 6 (where a higher id is newer). If a later poll increases the limit and returns objects 1-6, then 1, 2, and 3 will be (incorrectly) treated like new objects.

There's a more in-depth explanation here.

+

Each time a polling Zap runs, Zapier extracts a unique "primary key" for each item in the response. Zapier needs to decide which of the items should trigger the Zap. To do this, we compare the primary keys to all those we've seen before, trigger on new objects, and update the list of seen primary keys. When a Zap is turned on, we initialize the list of seen primary keys with a single poll. When it's turned off, we clear that list. For this reason, it's important that calls to a polling endpoint always return the newest items.

For example, the initial poll returns objects 4, 5, and 6 (where a higher primary key is newer). If a later poll increases the limit and returns objects 1-6, then 1, 2, and 3 will be (incorrectly) treated like new objects.

By default, the primary key is the item's id field. Since v15.6.0, you can customize the primary by setting any outputFields to true.

There's a more in-depth explanation here.

@@ -5639,6 +5641,36 @@

+
+
+

Since v15.6.0, instead of using the default id field, you can also define one or more outputFields as primary. For example:

+
+
+ 
{
+  triggers: {
+    recipe: {
+      operation: {
+        outputField: [
+          { key: 'userId', primary: true },
+          { key: 'slug', primary: true },
+        ]
+      }
+    }
+  }
+}
+
+
+
+
+
+
+

will tell Zapier to use (userId, slug) as the unique primary key to deduplicate items when running a polling trigger.

+
+
+ +
+
+

Node X No Longer Supported

diff --git a/packages/cli/README-source.md b/packages/cli/README-source.md index 3a78059a9..212ada4d0 100644 --- a/packages/cli/README-source.md +++ b/packages/cli/README-source.md @@ -786,9 +786,9 @@ On each trigger, search, or create in the operation directive - you can provide Output Fields are optional, but can be used to: - - Define friendly labels for the returned fields. By default, we will *humanize* for example `my_key` as *My Key*. - Make sure that custom fields that may not be found in every live sample and - since they're custom to the connected account - cannot be defined in the static sample, can still be mapped. +- (Added in v15.6.0) Define what field(s) can be used to uniquely identify and [deduplicate](#dedupe) items returned by a polling trigger call. The [schema](https://github.com/zapier/zapier-platform/blob/main/packages/schema/docs/build/schema.md#fieldschema) for `outputFields` is shared with `inputFields` but only the `key`, `label`, `type`, and `required` properties are relevant: @@ -796,6 +796,7 @@ The [schema](https://github.com/zapier/zapier-platform/blob/main/packages/schema - `label` - defines the field name displayed to users. - `type` - defines the type for static sample data. A [validation warning](https://platform.zapier.com/docs/integration-checks-reference#d024---static-sample-respects-output-field-definition) will be displayed if the static sample does not match the specified type. - `required` - defines whether the field is required in static sample data. A [validation warning](https://platform.zapier.com/docs/integration-checks-reference#d024---static-sample-respects-output-field-definition) will be displayed if the value is true and the static sample does not contain the field. +- `primary` - defines whether the field is part of the primary key for polling trigger [deduplication](#dedupe). Custom/Dynamic Output Fields are defined in the same way as [Custom/Dynamic Input Fields](#customdynamic-fields). @@ -2052,11 +2053,13 @@ Lastly, you need to set `canPaginate` to `true` in your polling definition (per ### How does deduplication work? -Each time a polling Zap runs, Zapier needs to decide which of the items in the response should trigger the zap. To do this, we compare the `id`s to all those we've seen before, trigger on new objects, and update the list of seen `id`s. When a Zap is turned on, we initialize the list of seen `id`s with a single poll. When it's turned off, we clear that list. For this reason, it's important that calls to a polling endpoint always return the newest items. +Each time a polling Zap runs, Zapier extracts a unique "primary key" for each item in the response. Zapier needs to decide which of the items should trigger the Zap. To do this, we compare the primary keys to all those we've seen before, trigger on new objects, and update the list of seen primary keys. When a Zap is turned on, we initialize the list of seen primary keys with a single poll. When it's turned off, we clear that list. For this reason, it's important that calls to a polling endpoint always return the newest items. + +For example, the initial poll returns objects 4, 5, and 6 (where a higher primary key is newer). If a later poll increases the limit and returns objects 1-6, then 1, 2, and 3 will be (incorrectly) treated like new objects. -For example, the initial poll returns objects 4, 5, and 6 (where a higher `id` is newer). If a later poll increases the limit and returns objects 1-6, then 1, 2, and 3 will be (incorrectly) treated like new objects. +By default, the primary key is the item's `id` field. Since v15.6.0, you can customize the primary by setting any `outputFields` to true. -There's a more in-depth explanation [here](https://platform.zapier.com/legacy/dedupe). +There's a more in-depth explanation [here](https://platform.zapier.com/build/deduplication). ### Why are my triggers complaining if I don't provide an explicit `id` field? @@ -2071,6 +2074,25 @@ return items.map((item) => { }); ``` +Since v15.6.0, instead of using the default `id` field, you can also define one or more `outputFields` as `primary`. For example: + +```js +{ + triggers: { + recipe: { + operation: { + outputField: [ + { key: 'userId', primary: true }, + { key: 'slug', primary: true }, + ] + } + } + } +} +``` + +will tell Zapier to use `(userId, slug)` as the unique primary key to deduplicate items when running a polling trigger. + ### Node X No Longer Supported If you're seeing errors like the following: diff --git a/packages/cli/README.md b/packages/cli/README.md index c1189d789..b35317ca5 100644 --- a/packages/cli/README.md +++ b/packages/cli/README.md @@ -1677,9 +1677,9 @@ On each trigger, search, or create in the operation directive - you can provide Output Fields are optional, but can be used to: - - Define friendly labels for the returned fields. By default, we will *humanize* for example `my_key` as *My Key*. - Make sure that custom fields that may not be found in every live sample and - since they're custom to the connected account - cannot be defined in the static sample, can still be mapped. +- (Added in v15.6.0) Define what field(s) can be used to uniquely identify and [deduplicate](#dedupe) items returned by a polling trigger call. The [schema](https://github.com/zapier/zapier-platform/blob/main/packages/schema/docs/build/schema.md#fieldschema) for `outputFields` is shared with `inputFields` but only the `key`, `label`, `type`, and `required` properties are relevant: @@ -1687,6 +1687,7 @@ The [schema](https://github.com/zapier/zapier-platform/blob/main/packages/schema - `label` - defines the field name displayed to users. - `type` - defines the type for static sample data. A [validation warning](https://platform.zapier.com/docs/integration-checks-reference#d024---static-sample-respects-output-field-definition) will be displayed if the static sample does not match the specified type. - `required` - defines whether the field is required in static sample data. A [validation warning](https://platform.zapier.com/docs/integration-checks-reference#d024---static-sample-respects-output-field-definition) will be displayed if the value is true and the static sample does not contain the field. +- `primary` - defines whether the field is part of the primary key for polling trigger [deduplication](#dedupe). Custom/Dynamic Output Fields are defined in the same way as [Custom/Dynamic Input Fields](#customdynamic-fields). @@ -3543,11 +3544,13 @@ Lastly, you need to set `canPaginate` to `true` in your polling definition (per ### How does deduplication work? -Each time a polling Zap runs, Zapier needs to decide which of the items in the response should trigger the zap. To do this, we compare the `id`s to all those we've seen before, trigger on new objects, and update the list of seen `id`s. When a Zap is turned on, we initialize the list of seen `id`s with a single poll. When it's turned off, we clear that list. For this reason, it's important that calls to a polling endpoint always return the newest items. +Each time a polling Zap runs, Zapier extracts a unique "primary key" for each item in the response. Zapier needs to decide which of the items should trigger the Zap. To do this, we compare the primary keys to all those we've seen before, trigger on new objects, and update the list of seen primary keys. When a Zap is turned on, we initialize the list of seen primary keys with a single poll. When it's turned off, we clear that list. For this reason, it's important that calls to a polling endpoint always return the newest items. + +For example, the initial poll returns objects 4, 5, and 6 (where a higher primary key is newer). If a later poll increases the limit and returns objects 1-6, then 1, 2, and 3 will be (incorrectly) treated like new objects. -For example, the initial poll returns objects 4, 5, and 6 (where a higher `id` is newer). If a later poll increases the limit and returns objects 1-6, then 1, 2, and 3 will be (incorrectly) treated like new objects. +By default, the primary key is the item's `id` field. Since v15.6.0, you can customize the primary by setting any `outputFields` to true. -There's a more in-depth explanation [here](https://platform.zapier.com/legacy/dedupe). +There's a more in-depth explanation [here](https://platform.zapier.com/build/deduplication). ### Why are my triggers complaining if I don't provide an explicit `id` field? @@ -3562,6 +3565,25 @@ return items.map((item) => { }); ``` +Since v15.6.0, instead of using the default `id` field, you can also define one or more `outputFields` as `primary`. For example: + +```js +{ + triggers: { + recipe: { + operation: { + outputField: [ + { key: 'userId', primary: true }, + { key: 'slug', primary: true }, + ] + } + } + } +} +``` + +will tell Zapier to use `(userId, slug)` as the unique primary key to deduplicate items when running a polling trigger. + ### Node X No Longer Supported If you're seeing errors like the following: diff --git a/packages/cli/docs/index.html b/packages/cli/docs/index.html index 9ebc84693..c1694ad11 100644 --- a/packages/cli/docs/index.html +++ b/packages/cli/docs/index.html @@ -2747,11 +2747,13 @@

Output Fields

On each trigger, search, or create in the operation directive - you can provide an array of objects as fields under the outputFields. Output Fields are what users see when they select a field provided by your trigger, search or create to map it to another.

Output Fields are optional, but can be used to:

  • Define friendly labels for the returned fields. By default, we will humanize for example my_key as My Key.
  • Make sure that custom fields that may not be found in every live sample and - since they're custom to the connected account - cannot be defined in the static sample, can still be mapped.
    • +
  • (Added in v15.6.0) Define what field(s) can be used to uniquely identify and deduplicate items returned by a polling trigger call.

The schema for outputFields is shared with inputFields but only the key, label, type, and required properties are relevant:

  • key - includes the field when not present in the live sample. When no label property is provided, key will be humanized and displayed as the field name.
  • label - defines the field name displayed to users.
  • type - defines the type for static sample data. A validation warning will be displayed if the static sample does not match the specified type.
  • required - defines whether the field is required in static sample data. A validation warning will be displayed if the value is true and the static sample does not contain the field.
    • +
  • primary - defines whether the field is part of the primary key for polling trigger deduplication.

Custom/Dynamic Output Fields are defined in the same way as Custom/Dynamic Input Fields.

@@ -5608,7 +5610,7 @@

How does deduplication work?

-

Each time a polling Zap runs, Zapier needs to decide which of the items in the response should trigger the zap. To do this, we compare the ids to all those we've seen before, trigger on new objects, and update the list of seen ids. When a Zap is turned on, we initialize the list of seen ids with a single poll. When it's turned off, we clear that list. For this reason, it's important that calls to a polling endpoint always return the newest items.

For example, the initial poll returns objects 4, 5, and 6 (where a higher id is newer). If a later poll increases the limit and returns objects 1-6, then 1, 2, and 3 will be (incorrectly) treated like new objects.

There's a more in-depth explanation here.

+

Each time a polling Zap runs, Zapier extracts a unique "primary key" for each item in the response. Zapier needs to decide which of the items should trigger the Zap. To do this, we compare the primary keys to all those we've seen before, trigger on new objects, and update the list of seen primary keys. When a Zap is turned on, we initialize the list of seen primary keys with a single poll. When it's turned off, we clear that list. For this reason, it's important that calls to a polling endpoint always return the newest items.

For example, the initial poll returns objects 4, 5, and 6 (where a higher primary key is newer). If a later poll increases the limit and returns objects 1-6, then 1, 2, and 3 will be (incorrectly) treated like new objects.

By default, the primary key is the item's id field. Since v15.6.0, you can customize the primary by setting any outputFields to true.

There's a more in-depth explanation here.

@@ -5639,6 +5641,36 @@

+
+
+

Since v15.6.0, instead of using the default id field, you can also define one or more outputFields as primary. For example:

+
+
+ 
{
+  triggers: {
+    recipe: {
+      operation: {
+        outputField: [
+          { key: 'userId', primary: true },
+          { key: 'slug', primary: true },
+        ]
+      }
+    }
+  }
+}
+
+
+
+
+
+
+

will tell Zapier to use (userId, slug) as the unique primary key to deduplicate items when running a polling trigger.

+
+
+ +
+
+

Node X No Longer Supported