Merge pull request #544 from zapier/making_changes

PLATSUPP-998_Docs Overhaul

docs/_build/hydration.md → docs/_build/advanced-features/hydration.md

@@ -1,6 +1,6 @@
 ---
 title: Use hydration in Platform CLI
-order: 19
+order: 5
 layout: post-toc
 redirect_from: /cli_tutorials/hydration
 ---

docs/_build/testing/test-triggers-actions.md

@@ -23,7 +23,14 @@ Once authentication is tested, trigger and action steps are easy to test inside
 2. Fill in details for each of the input fields in the _Configure Test Data_ form. Add data that will successfully work in this API call, similar to what you would use in a live Zap.
 3. Enter individual values in each field to add single objects. If you include commas in the field data, Zapier will turn that field into an array sent to your API. Select _Raw_ to preview the JSON formatted data.
 4. Select _Test Your Request_ to run the trigger or action step, verify it ran successfully and show the JSON results which you can explore as in the Authentication testing.
-5. When testing a [REST Hook trigger](https://platform.zapier.com/build/hook-trigger), you will instead have to create and test a Zap in the Zap Editor as follows:
+5. If an error is returned, check the following:
+
+    - Authentication: Did your app's authentication work correctly in the authentication step? You can only test an integration once you've connected an app account to Zapier.
+    - Test Data: Did your test data include the details your app expects, such as actual dates in date fields or complete email addresses in email address fields?
+    - Input Field Keys: Did you use the same field keys in your input field as your API expects? Double-check that in the Input Designer, and change if needed.
+    - API Call Customization: Does your API expect something different than the standard API call details Zapier sets by default? You may need to use Code Mode if the options you need aren't available.
+
+6. When testing a [REST Hook trigger](https://platform.zapier.com/build/hook-trigger), you will instead have to create and test a Zap in the Zap Editor as follows:
 
     - Test the trigger to confirm that the Perform List works and provides live data from the app.
     - Turn on the Zap to confirm that the subscription is successful.

docs/_build/triggers/cli-hook-trigger.md

@@ -9,6 +9,8 @@ redirect_from: /cli_tutorials/resthooks
 
 REST Hooks are an alternative to polling. The main differences are allowing your customers' Zaps to trigger instantly; and avoiding polling triggers' numerous - and sometimes unnecessary - requests to your API's endpoints to check for new data. 
 
+REST Hook triggers are marked as _Instant_ [in the Zap editor](https://cdn.zappy.app/f510859bf90c0e341bc94997a75f9626.png).
+
 When building in the [Platform CLI](https://platform.zapier.com/quickstart/ui-vs-cli), use the [example implementation](https://github.com/zapier/zapier-platform/tree/main/example-apps/rest-hooks) for guidance.
 
 With a REST Hook trigger, Zapier subscribes to your server using a unique URL per activated Zap and your app sends a payload of data back to the unique URL to trigger that particular Zap whenever that trigger event occurs in your app.

docs/_build/triggers/hook-trigger.md

@@ -49,6 +49,8 @@ On the API Configuration page, select **REST Hook** as the trigger type, and com
 
 ![](https://cdn.zappy.app/0368aeae12e11ec59688d10a7ef69d8c.png)
 
+REST Hook triggers are marked as _Instant_ [in the Zap editor](https://cdn.zappy.app/f510859bf90c0e341bc94997a75f9626.png).
+
 ### Subscribe
 This request, usually a POST, is performed when a user activates a Zap that starts with this REST Hook trigger. This is how a Zap makes a subscription request to your API to be notified (via webhook) of all trigger events with the given parameters going forward.
 
@@ -104,10 +106,10 @@ For data sent to Zapier via REST Hook, most requests will be successful and retu
 
 Once you've configured all the endpoints, click _Save API Request & Continue_
 
-## 4. Test your API Request
+## 4. Test your API request
 
 To test the REST Hook trigger, [build a Zap in the editor](https://platform.zapier.com/build/test-triggers-actions).
 
-## 5. Define your Output
+## 5. Define your output
 
 Define sample data and output fields following [the guide](https://platform.zapier.com/build/sample-data).

docs/_build/triggers/polling-trigger.md

@@ -57,10 +57,10 @@ Only if you plan to use this trigger to power dynamic dropdown menus in other Za
 
 Once you've added your trigger settings, click _Save API Request & Continue_.
 
-## 4. Test your API Request
+## 4. Test your API request
 
 Configure test data to [test the polling trigger](https://platform.zapier.com/build/test-triggers-actions).
 
-## 5. Define your Output
+## 5. Define your output
 
 Define sample data and output fields following [the guide](https://platform.zapier.com/build/sample-data).

docs/_build/triggers/reorder-trigger.md

@@ -7,7 +7,7 @@ redirect_from:
 
 # Reorder or remove triggers
 
-## Reordering Triggers
+## Reordering triggers
 
 Triggers are listed in alphabetical order in the Zap editor and this order cannot be changed. 
 
@@ -23,7 +23,7 @@ To change a trigger's visibility:
 
 ![](https://cdn.zappy.app/51c3b8911b5384ddf03b9dbfffd40050.png)
 
-## Removing Triggers
+## Removing triggers
 
 You may want to remove a trigger that your app no longer supports, or fully rebuild a new one in place of the previous one.
 

docs/_manage/integration-changes/auth-keys.md

@@ -0,0 +1,49 @@
+---
+title: Change authentication field keys
+order: 4
+layout: post-toc
+redirect_from: /manage/making-changes#changing-authentication-field-keys
+---
+
+# Change authentication field keys
+
+## Change scenario
+
+You want to change the key of one or more [authentication input fields](https://platform.zapier.com/build/basicauth#1-build-an-input-form) required when a user authenticates your app to Zapier.
+
+## Impact to users
+
+This is a **breaking change**.
+
+Modifying the key of an existing authentication field constitutes a breaking change. Without adequate precautions, existing app connections may break as [migration](https://platform.zapier.com/manage/migrate) is not possible. Users will need to establish a new connection to your integration and manually refresh each of their Zaps.
+
+## Best practices
+
+We strongly encourage you to **avoid changing authentication field keys** whenever possible.
+
+### Workaround
+
+If your API endpoint requires a different property for authentication, think about adjusting the property key rather than amending the form field input’s key.
+This modification must be made in each trigger, action, search request, as well as in the authentication.
+
+>NOTE: Form field input keys do not need to match directly with the properties your API expects.
+
+For example, let's say you have a form field input with the key `API-KEY`and are sending the field's value to your API using the same property name of `API-KEY`. 
+
+![](https://cdn.zappy.app/daef0487a89a2cbb17ec719cbbd50577.png)
+
+```
+headers: {
+  "API-KEY": bundle.authData.api_key; // original
+}
+```
+
+Next, your API changes and expects the request property to be `X-API-KEY` instead. You can change the request property key (left) as needed. But still refer to the original form field input (right). 
+
+![](https://cdn.zappy.app/bf4cdfe3183752e0e57707001260e9e3.png)
+
+```
+headers: {
+  "X-API-KEY": bundle.authData.api_key; // new - request key and field key can differ
+}
+```

docs/_manage/integration-changes/auth-required.md

@@ -0,0 +1,42 @@
+---
+title: Add required authentication field
+order: 3
+layout: post-toc
+redirect_from: /manage/making-changes#adding-a-required-auth-field
+---
+
+# Add required authentication field
+
+## Change scenario
+
+You'd like to add, remove, or change an optional input field to be required in your current authentication schema. 
+
+## Impact to users
+
+This will cause a breaking change which will have the following significant effects to users:
+- Existing connected accounts will not work: All existing connected accounts will no longer be functional with your integration until users re-authenticate manually.
+- Manual updates are required for all Zaps: Zaps cannot be migrated due to a breaking change, users will have to edit each Zap individually before they can start running tasks again. For example, if a user has 20 Zaps set up with your integration, they will need to manually update each one of those Zaps.
+
+## Best practices
+
+- **Add the field as optional:** Use field [help text](https://platform.zapier.com/build/build/basicauth#1-build-an-input-form) and [custom error handling](https://github.com/zapier/zapier-platform/blob/main/packages/cli/README.md#error-handling) (if you're using our Code Mode or the CLI platform) to validate that the newly required field is provided, while keeping it set to optional. Also, consider using custom code to set the field’s default value in your API call if left blank.
+- **Set a default value:** If possible, provide a default value for the required field that can be overwritten if necessary. This ensures that users who do not provide explicit values for these fields can continue to use your integration without issues.
+
+For example in the case of updated API endpoints for geographical region or site domain, it is possible to account for an added **required** inputField with scripting to ensure existing authentications are backward compatible, allowing existing users to be migrated to the new version.
+
+In this example code, the default URL for US region is updated when the user selects AU or CA when authenticating.
+
+```
+let baseURL = "theUsApiBaseUrl";
+switch (authData.region) {
+  case "AU":
+    baseURL = "theAuApiBaseUrl";
+    break;
+  case "CA":
+    //other regions can be easily supported by adding cases like this
+    baseURL = "theCaApiBaseUrl";
+    break;
+  default:
+    console.log("Legacy credentials are in use, defaulting to US Base URL.");
+}
+```

docs/_manage/integration-changes/auth-scheme.md

@@ -0,0 +1,32 @@
+---
+title: Change authentication scheme
+order: 2
+layout: post-toc
+redirect_from: /manage/making-changes#changing-authentication-scheme
+---
+
+## Change scenario
+
+If your API’s authentication method changes, or your app rolls out different endpoints for integration users; you would need to change the method Zapier uses to authenticate user accounts.
+
+## Impact to users
+
+Changing the authentication type (e.g., Basic Auth, API Key, or OAuth) of an integration is regarded as a breaking change. Notably, migration is impracticable since all pre-existing connected accounts would stop working if migrated. Users would need to make a new connection to your integration and manually modify each of their Zaps.
+
+## Best practices
+
+**Creating a New Version**
+- [Clone](https://platform.zapier.com/manage/clone) your app, generating a new version.
+- [Remove](https://platform.zapier.com/build/auth#how-to-remove-or-change-zapier-integration-authentication-scheme) the existing authentication method and incorporate the new one.
+- Once configured, [promote](https://platform.zapier.com/manage/promote) this version, making it available for new users to select during the connection of your integration to Zapier.
+
+**Managing Existing Users**
+- If users with existing authentications can retain their connection using the old method, enabling them to stick to the old version is recommended.
+- However, they will be prompted to form a new connection for any new Zaps since only the promoted version is available during a name-based app search.
+
+
+**Deprecating legacy authentication scheme**
+- If existing authentications are set to be non-functional in the future, then [Deprecation](https://platform.zapier.com/manage/deprecate) is required.
+- Be mindful that this can be notably disruptive for our mutual users and thus should be considered carefully.
+
+>NOTE: this method is not possible with apps built in the legacy web builder. To update the authentication, you would need to update all triggers/actions/searches as well; as deleting the authentication method and re-adding it in the new builder would not be compatible with existing triggers/actions/searches built in the legacy web builder.

docs/_manage/integration-changes/change-api.md

@@ -0,0 +1,32 @@
+---
+title: Changes to your API can impact your integration
+order: 12
+layout: post-toc
+redirect_from: /manage/making-changes#making-changes-to-your-api
+---
+
+# Changes to your API can impact your integration
+
+## Change scenario
+
+When making changes to your API, consider how these will affect your Zapier integration. API updates can vary from small to significant changes and can have varying effects on your users’ Zaps.
+
+## Impact to users
+
+Though not exhaustive, here are some potential major impacts to users:
+
+- If a new version with breaking changes to authentication is promoted, users with existing Zaps will have to manually reconnect their account on Zapier.
+- If a new version with breaking changes to any trigger, action, or search is promoted, users with existing Zaps will have to manually upgrade _each_ Zap using your integration. Keep in mind: power users can have tens to hundreds of Zaps using your integration.
+- Changes to a trigger, action, or search’s response data can break or negatively affect the proceeding steps of the Zap.
+- Changes to response data in polling triggers can prevent Zaps from triggering on new records or cause them to trigger on old records. This can lead to missed data and undesirable results for your users.
+
+## Best practices
+
+To mitigate the impact of API changes on your Zapier users, consider the following best practices:
+
+- Maintain general backwards compatibility on existing endpoints. This ensures that the existing Zaps continue to work as expected, and your users won't need to modify them due to API changes.
+- For polling triggers - changing the number of records returned from the endpoint can significantly impact the functionality of the users' Zaps.
+- Implementing pagination on an endpoint can affect how much data is fetched and processed when a Zap polls that endpoint.
+- Changing the sort order of response data returned can impact Zap triggers. For polling triggers, ensure that the data is always sorted in reverse chronological order to maintain compatibility.
+
+By adhering to these best practices, you can minimize disruptions to your Zapier users when updating or modifying your API. A well-managed API transition process ensures that your users continue to have a seamless and efficient Zapier integration experience.

docs/_manage/integration-changes/change-keys.md

@@ -0,0 +1,59 @@
+---
+title: Change trigger or action key
+order: 5
+layout: post-toc
+redirect_from: /manage/making-changes#updates-to-triggeractionsearch-keys
+---
+
+# Change trigger or action key
+
+## Change scenario
+
+In cases where a trigger/action/search’s custom code needs to be rewritten or a new v2 is replacing an older v1.
+
+## Impact to users
+
+Deleting a trigger/action/search in a new version is a breaking change - which would prevent migration of your users to the new version. Updating an existing trigger/action/search’s custom code would allow for migration but break users’ Zaps if the output changes.
+
+![impact example](https://cdn.zappy.app/65326a8f5fff0f9640c0d6fdc59dfa3b.png)
+
+The triggers, actions, and searches are identified by their **key**, such as `new_contact` or `create_post`, so if you remove that key from the app's definition, or change it (possible in CLI apps only), this message appears when you attempt to migrate.
+
+## Best practices
+
+- If you have already renamed the **key** (possible in CLI apps only) for a trigger/action/search, you’ll need to switch it back to the previous **key** to proceed with migrating users.
+- If you need to remove a trigger/action/search, change its visibility to **hidden** instead. Use the Visibility Options dropdown in the [UI](https://platform.zapier.com/polling-trigger#1-add-the-trigger-settings), or the `hidden` key in the [CLI](https://github.com/zapier/zapier-platform/blob/main/packages/schema/docs/build/schema.md#basicdisplayschema).
+
+![hidden](https://cdn.zappy.app/73990d8049572347aea87fc304173ecc.png)
+
+Migrated Zaps that used the hidden trigger/action/search will now show it as Deprecated in the Zap editor, but will continue to function as long as the endpoints remain valid.
+
+![deprecated](https://cdn.zappy.app/61a2ac6095433d278bc412c2e59408fc.png)
+
+Once a user selects a different trigger/action/search when editing their Zap, they will not be able to retrieve the hidden one. New users will not see any `hidden` trigger/action/search as available for selection.
+
+- If you need to add a new trigger/action/search that replaces the hidden one, create a duplicate and give it a new **key** (such as appending `_v2` on the end), and keep the Name and Description the same if the functionality for a user is the same.
+
+![duplicate](https://cdn.zappy.app/6231ec2b53271c7d83672f6ed232d0e3.png)
+
+- This way existing Zaps continue to work once migrated with the previous (and now hidden) definition, and new Zaps will only be able to select the new definition.
+
+- In cases where the endpoint in the hidden trigger/action/search will be sunset and begin to return errors in the future, the impact to users would be as follows:
+
+Once the API has been sunset, active Zaps (turned on) using the impacted trigger/action/search will produce errors when they run. Depending on [user's email notification settings](https://help.zapier.com/hc/en-us/articles/8496289225229), owners of these Zaps will be sent email notifications about these errors.
+
+If those Zaps exceed the error ratio **and** users have not [overridden related settings in their Zaps](https://help.zapier.com/hc/en-us/articles/8496037690637-Troubleshoot-errors-in-Zapier#i-want-my-zap-to-continue-running-even-when-there-are-errors--0-6), those Zaps will be automatically turned off.
+
+- If you’d like to add custom errors within Zapier for the hidden trigger/action/search at the time of the endpoint sunset, you could consider the following:
+
+Create a new version of the integration that immediately throws a `z.errors.Error` exception in the `perform` method of the impacted trigger/action/search. Learn more for apps maintained in the [UI](https://platform.zapier.com/manage/making-changes#custom-error-handling-in-the-ui) or the [CLI](https://github.com/zapier/zapier-platform/blob/main/packages/cli/README.md#zerrors).
+
+_Promote_ and then _migrate_ users to this new version as close to the sunset date as possible.
+
+The benefits of this approach are:
+
+-- Throwing an explicit exception will ensure impacted Zaps will hit the error ratio (and be turned off) at the earliest possible time.
+-- You can add a user-friendly message to the exception that users will see in both Zaps Runs on the [Zap History](https://help.zapier.com/hc/en-us/articles/8496291148685-View-and-manage-your-Zap-history) and also in email error notifications, e.g. _This function has been deprecated and is no longer available._
+-- Here's an example of how a custom error message would be displayed on an action in the Zap History:
+
+![custom error](https://cdn.zappy.app/50807aad2a2e2ecda9044a524dafba8c.png)