Merge pull request #566 from zapier/publish_edits

PLATSUPP-1007_Docs Overhaul fixes

docs/_build/actions/action.md

@@ -12,7 +12,7 @@ redirect_from:
 
 Every Zap starts with a single trigger that watches for new or updated data, starting the user's workflow. Action steps then make use of that data.
 
-Zapier actions create or update new data into apps through API calls that pass data from user customized [input fields](https://platform.zapier.com/build/add-fields). 
+Zapier actions create or update a single item in your app through API calls that include multiple details from user customized [input fields](https://platform.zapier.com/build/add-fields). 
 
 ![Zapier Action Visual Builder](https://cdn.zappy.app/57f28534d180f2a642ebe0be2e236c32.png)
 
@@ -22,16 +22,26 @@ There are two types of actions to select.
 
 ## 1. Create actions
 
-Most Zapier integrations should at a minimum include create actions to let users add items to their app automatically. Common actions by app category [here](https://platform.zapier.com/quickstart/integration-design-examples) should be used for inspiration when building your app.
+Most Zapier integrations should at a minimum include create actions to let users add items to their app automatically. Common actions by app category [here](https://platform.zapier.com/quickstart/must-have-triggers-and-actions) should be used for inspiration when building your app.
 
 _Create_ actions in Zaps can create new items in an app or update existing items. The output returned should be an object containing individual fields that will be parsed for mapping into subsequent Zap steps.
 
+The [output returned](https://platform.zapier.com/build/response-types) by a _create_ should be an object containing individual fields about the item that was created such as IDs, details about the new item including a link if possible, and any other useful data about the record. Do not return just a `success` message. 
+
+Unsucessful actions should return `4xx` errors. If your API returns a `2xx` error, add custom code to your API call to replace it with a correct error.
+
+Update actions should be separate from create actions.
+
+Actions may create multiple items if needed, using the same data, though you will likely need to customize the API call code to create multiple items at once. Only do this for linked items, such as if an app stores customers and customer addresses separately.  If the multiple items that need to be created are top-level, complex items in your app, they should be separate actions within Zapier. You can then link the two with a drop-down menu in the action to select the paired item, add a search action for users to find the specific item they need, and then let them match the items with the [_Use a Custom Value_ option](https://help.zapier.com/hc/en-us/articles/8496241696141) in Zapier.
+
 ## 2. Search actions
 
-_Search_ actions find existing items in an app and can optionally be paired with _create_ actions to add a new item if the search does not return a result.
+_Search_ actions find existing items in an app and can optionally be paired with _create_ actions to [add a new item](https://platform.zapier.com/build/search-or-create) if the search does not return a result.
 
 Search actions let users do more with the data they’ve already added to your app; such as avoiding adding duplicate items or look up info about an item, for example weather, conversion, and contact lookup, to use in a subsequent step. 
 
-The output returned by a _search_ should be a JSON-formatted array sorted with the best match first. Only the first item will be returned. For no match found, a `200` with an empty array must be returned. 
+Most useful searches return one individual item that will likely be needed in another Zap step.
+
+The [output returned](https://platform.zapier.com/build/response-types) by a _search_ should be a JSON-formatted array sorted with the best match first. Only the first item will be returned. For no match found, a `200` with an empty array must be returned. If your API returns a `404` error for searches without results, add custom code to your API call to replace it with an empty array. 
 
 Zapier strongly recommends against action steps that delete or remove data. To prevent data loss, action steps should only add or update data. If you are considering adding a delete action to your app, consider alternative actions for items such as deactivating, unsubscribing, or canceling, instead of deleting items completely.

docs/_build/actions/create.md

@@ -19,11 +19,11 @@ redirect_from:
 
 -- **Key**: A unique identifier for this action, used to reference the action inside Zapier. Does not need to be the same identifier as used in your API. Not shown to users.
 
--- **Name**: A human friendly plain text name for this action, typically with a verb such as _Add_ or _Create_ followed by the name of the item this action will create in your app. Shown inside the Zap editor and on Zapier's app directory marketing pages.
+-- **Name**: A human friendly plain text name for this action, typically with a verb such as _Add_ or _Create_ followed by the name of the item this action will create in your app. The title-case name is shown inside the Zap editor and on Zapier's app directory marketing pages.
 
 -- **Noun**: A single noun that describes what this action creates, used by Zapier to auto-generate text in Zaps about your action.
 
--- **Description**: A plain text sentence that describes what the action does and when it should be used. Shown inside the Zap editor and on Zapier's app directory marketing pages.
+-- **Description**: A plain text sentence that describes what the action does and when it should be used. Shown inside the Zap editor and on Zapier's app directory marketing pages. Starts with the phrase "Creates a new". 
 
 -- **Visibility Options**: An option to select when this action will be shown. _Shown_ is chosen by default. Choose `Hidden` if this action should not be shown to users. `Hidden` is usually selected if you build a _create_ action solely to [pair with a search action](https://platform.zapier.com/build/search-create-action) but do not want it used on its own.
 

docs/_build/actions/search.md

@@ -19,11 +19,11 @@ redirect_from:
 
 -- **Key**: A unique identifier for this action, used to reference the action inside Zapier. Does not need to be the same identifier as used in your API. Not shown to users.
 
--- **Name**: A human friendly plain text name for this action, typically with a verb such as _Find_ or _Search_ followed by the name of the item this action will find in your app. Shown inside the Zap editor and on Zapier's app directory marketing pages.
+-- **Name**: A human friendly plain text name for this action, typically with a verb such as _Find_ or _Search_ followed by the name of the item this action will find in your app. The title-case name is shown inside the Zap editor and on Zapier's app directory marketing pages.
 
 -- **Noun**: A single noun that describes what this action searches, used by Zapier to auto-generate text in Zaps about your action.
 
--- **Description**: A plain text sentence that describes what the action does and when it should be used. Shown inside the Zap editor and on Zapier's app directory marketing pages.
+-- **Description**: A plain text sentence that describes what the action does and when it should be used. Shown inside the Zap editor and on Zapier's app directory marketing pages. Starts with the phrase "Finds a". 
 
 -- **Visibility Options**: An option to select when this action will be shown. _Shown_ is chosen by default. 
 

docs/_build/authentication/apikeyauth.md

@@ -13,7 +13,7 @@ API Key authentication passes along a user-entered API Key with every API call.
 ![Zapier API Key auth example](https://cdn.zapier.com/storage/photos/19467b7d1852276b766b373373fd069c.png)
 _Example API Key auth screen for users inside Zapier_
 
-Use API Key authentication if your API primarily uses an API Key to identify accounts, especially with apps for weather, maps, content verification, file conversion, and other data tools that require a key for access to the service but do not contain user-specific content. 
+Use API Key authentication if your API primarily uses an API key to identify accounts, especially with apps for weather, maps, content verification, file conversion, and other data tools that require a key for access to the service but do not contain user-specific content. 
 
 Since API Key authentication allows you to create a custom input form, you can use it for any custom authentication type with username and password-based logins that don't fit other authentication scheme types.
 
@@ -41,7 +41,7 @@ Since API Key authentication allows you to create a custom input form, you can u
 
 -- **Type**: All input fields use the `string` text field by default; select `password` instead if you would like to obscure the data as users enter it.
 
--- **Help Text**: Include details to assist users in authenticating with your app, especially if they may be unsure where to find the data needed within your app. Format text with [Markdown](https://zapier.com/blog/beginner-ultimate-guide-markdown/), and include a hyperlink if needed.
+-- **Help Text**: Include a direct URL formatted with [Markdown](https://zapier.com/blog/beginner-ultimate-guide-markdown/) where users can obtain their API key from your app. If there is no direct link, include as clear of directions as possible to help users find the API key.
 
 -- **Input Format**: (optional) Help users figure out exactly what piece of data you need them to enter. For example, for a subdomain, https://{{input}}.yourdomain.com/.
 
@@ -59,11 +59,11 @@ Since API Key authentication allows you to create a custom input form, you can u
 
 ## 2. Add a Test API Request
 
-- Add an API call to your API that requires no configuration, typically a `/user` or `/me` call. Add the URL for the API call, and set the call type, typically a `GET`. This will test the user-entered API Key and any other credentials to ensure it enables a successful API call to your app. 
+- Add an API call to your API that requires no configuration, typically a `/user` or `/me` call. Add the URL for the API call, and set the call type, typically a `GET`. This will test the user-entered API key and any other credentials to ensure it enables a successful API call to your app. 
 
 ![Zapier test request API Key authentication](https://cdn.zappy.app/c4c58979ddcf7eb8a462ac5ff7a37348.png)
 
-- The API Key and any additional input fields are automatically included in the URL Params and the HTTP Headers. Click _Show Options_ to remove the details where they are not needed. It is typically not recommended to pass any sensitive information such as the API Key in the URL Params. Passing it through the headers or even the body is preferable.
+- The API key and any additional input fields are automatically included in the URL Params and the HTTP Headers. Click _Show Options_ to remove the details where they are not needed. It is typically not recommended to pass any sensitive information such as the API key in the URL Params. Passing it through the headers or even the body is preferable.
 
 - To customize the test API request, select _Switch to Code Mode_ and write custom JavaScript code to handle your test API call and the response parsing as needed. The first time you click the toggle, Zapier will convert your API call to code. If you switch back to Form Mode though, Zapier will not convert your code changes to the Form mode, nor will any subsequent changes in the form be added to your code.
 

docs/_build/authentication/auth.md

@@ -31,6 +31,12 @@ Zapier supports the following five authentication schemes in the Platform UI, ea
 
 ![Zapier Authentication](https://cdn.zappy.app/37e7829169eb2e07278d512c174cd708.png)
 
+Where possible, OAuth v2 authentication is the preferred scheme to simplify a user's account connection and minimize set up time. During the authentication flow via Zapier, a familiar popup window appears from your app to select their account or log in, then verify the connection. This fits the flow most modern apps use for integration authentication.
+
+API Key authentication is next best. Users must be able to obtain their API key from your app without human intervention. Your integration won't be [approved for publishing](https://platform.zapier.com/quickstart/private-vs-public-integrations) if your service requires users to email or call your team in order to receive an API key or access to your API.
+
+Basic authentication, while acceptable, is the least appropriate authentication type to use for a third party service like Zapier, as users must type their account credentials directly into Zapier's UI.
+
 For more custom authentication schemes, switch to the [Platform CLI](https://platform.zapier.com/manage/export-integration). 
 
 ## How to Remove or Change Type of Authentication Scheme 

docs/_build/authentication/sessionauth.md

@@ -24,7 +24,7 @@ Use Session authentication with your Zapier integration if your API is designed
 
 - Session auth does not include any default input fields. Add the fields required by your API by selecting _Add Fields_ and fill in the details for each field. Add the most commonly needed fields first, in the order users expect, as you cannot reorder fields once added. 
 
-- Two types of fields are available when building an OAuth v2 input form. Standard Fields, work much like other form fields with Zapier's [input form](https://platform.zapier.com/build/input-designer) in triggers and actions. [Computed Fields](https://platform.zapier.com/build/authentication/computed-fields) make sure specific fields are returned by your app's authentication API call response.
+- Two types of fields are available when building an Session input form. Standard Fields, work much like other form fields with Zapier's [input form](https://platform.zapier.com/build/input-designer) in triggers and actions. [Computed Fields](https://platform.zapier.com/build/authentication/computed-fields) make sure specific fields are returned by your app's authentication API call response.
 
 - For each field, add the required _Key_, the name your API uses to reference this field.
 

docs/_build/fields/add-fields.md

@@ -9,7 +9,7 @@ redirect_from:
 
 When building in the Platform UI, you'll use the Input Designer to create the form users will input data into, to send to your app's API.
 
-The Input Designer works similarly to other form builder tools, building a form that lives inside the Platform UI. Add fields to your form for each bit of data your app needs from users. Configure each field's settings, then reorder them to match the logical order users would add data in your app.
+The Input Designer works similarly to other form builder tools, building a form that lives inside the Platform UI. Add fields to your form for each bit of data your app needs from users. Use the same name for items as used in your app's UI. Configure each field's settings, then reorder them to match the logical order users would add or view data in your app.
 
 ![Example Input Editor](https://cdn.zappy.app/524b9300c044809eb13eb732d7a50f9d.png)
 
@@ -32,7 +32,7 @@ In this guide we will cover:
 
 - **Key**: A unique identifier for the field, without spaces, ideally with the same key as your API, such as `first_name`.
 - **Label**: A user friendly name for the field, such as `First Name`.
-- **Help Text**: (optional) A 20 character or longer description that appears under the field label, with [Markdown](https://zapier.com/blog/beginner-ultimate-guide-markdown/) formatting.
+- **Help Text**: (optional) A 20 character or longer description that appears under the field label, with [Markdown](https://zapier.com/blog/beginner-ultimate-guide-markdown/) formatting. Do not include redundant help text in input fields that repeats the name of the field. Use field help text to tell users what to do, for example "Choose the directory to watch for new files". Always use active voice. 
 - **Type**: From the dropdown menu, select type of data you want user's to enter. Learn more in [field definitions and types](https://platform.zapier.com/build/field-definitions):
     - String
     - Text
@@ -68,7 +68,7 @@ If users could add multiple entries in the same field, check the _Allows Multipl
 
 ![Zapier Field Allows Multiples](https://cdn.zappy.app/bf4c2a6ad55c12f6e3079e50f5d38e6c.png)
 
-That will add another entry row to allow the user to input another entry for that field. Each entry is then included in a comma separated list in the API request.
+That will add another entry row to allow the user to input another entry for that field. Each entry is then included in a comma separated list in the API request. Never ask users to type in a comma separated list, rather use this functionality. 
 
 ### Alters dynamic fields
 
@@ -121,7 +121,7 @@ For example, if your API expects a value of `1` or `2`, but `1` actually means `
 
 #### Dynamic Dropdown
 
-If users need to select data from their account in your app — such as a project, folder, team member, or other user-specific detail — then you would use a dynamic dropdown. For dynamic dropdowns, Zapier first fetches data from your API and then displays it in a menu.
+If users need to select data from their account in your app — such as a project, folder, team member, or other user-specific detail with a corresponding ID — then you would use a dynamic dropdown. For dynamic dropdowns, Zapier first fetches data from your API and then displays it in a menu. Never make users type in an ID number, rather use this functionality or [add a search action](https://platform.zapier.com/build/search) to find the ID number automatically.
 
 The best way to make a dynamic dropdown is to use a dedicated trigger to fetch the values for the menu. 
 

docs/_build/fields/sample-data.md

@@ -1,5 +1,5 @@
 ---
-title: Defining sample data and output fields
+title: Output data, defining sample data and output fields
 order: 5
 layout: post-toc
 redirect_from: 
@@ -8,9 +8,31 @@ redirect_from:
     - build/faq/#output-fields
 ---
 
-# Defining sample data and output fields
+# Output data, defining sample data and output fields
 
-This guide will explain what sample data and output fields are and how to modify them in your triggers or actions. 
+This guide will explain what output data, sample data and output fields are and how to modify them in your triggers or actions. 
+
+## Output data
+
+Each Zap step must return data to Zapier to use in subsequent steps. By default, the output data is the direct response from your API—but in some cases, you may need to customize the response data to make it work well with Zapier. Here are general principles for output data from your Zap steps:
+
+**Separate data where possible**, to make it as widely usable as possible in subsequent Zap steps. Names should be split into separate first/last or given/surname pairs, along optionally with a full name field. Addresses should be separated into their individual components.
+
+<a id="date"></a>
+**Format Date-time values in [ISO 8601](http://www.cl.cam.ac.uk/~mgk25/iso-time.html#date) standard including time zone offset**, even for UTC times. Avoid UNIX or Epoch timestamps. Date responses may be modified in your API call custom code if your API returns dates in different formats. Example acceptable date-time values include:
+
+- `2023-12-15T01:15:13Z` (or `-0000` instead of `Z`)
+- `2023-12-01T12:32:01-0800`
+- `2023-12-01T12:32:01-08:00`
+- `2023-12-13` (for date-only values)
+
+**Optionally include an additional human-friendly date** especially for scheduling or calendar app integrations where the date is important for users.
+
+**Set boolean values as `true` or `false`**. Do not use `1` and `0` for boolean values.
+
+**Include the value name and ID in lists and dropdown menus** to help users know which item to choose.
+
+**Consider removing non-necessary fields that may seem confusing to users** in your API call's custom code.
 
 ## Sample data