Action Fields#

Overview#

Action Fields answer the question: what details can a user provide when setting up an Action?

These details might include:

  • Title (EG: Note Title in Evernote)
  • Description (EG: Issue Description in Github)
  • Parent Object (span relationships via dynamic dropdowns)
  • Repo for an Issue (EG: Github)
  • Notebook for a Note (EG: Evernote)
  • Message Body (EG: Chat Body in Campfire or Hipchat)

What a user sees:

What a developer sees:

Each action should have at least one action field, because, hey, it really makes no sense to POST nothing to an endpoint!

You can also dynamically load custom action fields by inspecting a custom field endpoint of your own. Learn more.

Action Field Options#

Key#

A key for you and your API's consumption. This is available for variable syntax in the Action URL field as well as being added to the POSTed JSON (optional). Needs to be at least two characters long, start with an alpha, and only contain a-z, A-Z, 0-9 or _.

Example:
room

We'll take double underscores and convert them to nested dictionaries before we POST JSON.

Example:
project__title converts to {"project": {"title": "some value"} }

Label#

A human readable Label shown in the UI as a user works to complete an Action.

Example:
Room or Title

label help default

Help Text#

Human readable description of an action field, useful for describing some detail you couldn't list in the Label.

Example:
Choose which room to send the message to. or Add a title to the note.

Default#

A default value for a field. The behavior varies between required and optional fields. For required fields, the default will be set once when the user first creates the Action, but it is not guaranteed after that (we raise an error on missing/null values instead). For optional fields, it is set on initial creation and used in place of missing or null values every time the Zap runs.

Type#

The type we will try to coerce to on the backend. Fails silently to ensure that tasks aren't dropped on coercion errors.

You can get a full list of supported types and the coercion implied here: Field Types.

Required#

If checked a user will not be able to continue without entering some value.

Dynamic Dropdown#

Use an existing Trigger to load in values for selection, using the machine readable value your API consumes (like id or hash) while showing a human readable version to the user (like name or itemName).

Refer to our dynamic dropdown docs for a more in depth explanation.

Example:
TRIGGERKEY.id.name or TRIGGERKEY.hash.itemName

dynamic dropdown

Static Dropdowns#

A comma separated string that will be turned into a select field for limiting the choices a user can provide to an action field.

Example:
choice_a,choice_b,choice_c or Yesterday, Today, Tomorrow

simple static dropdown

If you would like to provide a label for the raw value of each choice, you can also use the raw|label,raw|label syntax instead.

Example:
1|Option 1,2|Option 2

simple static dropdown as key-value pairs

Search Connector#

Use an existing Search to find a value based on user input. Set the key of this field to the same key as the field in the search you want to use in executing the search. The second part of the definition is the attribute of the returned object that is sent to your service in place of this field.

Example:
SEARCHKEY.id

The above definition sets the field as an input to SEARCHKEY (as long as the field key matches a field key within SEARCHKEY), and the id field from the first result returned from SEARCHKEY is used as the value for this field.

The user does not see anything different for this type of field, so make sure to explain in the help text what kind of input you expect here.

Note: Any field with a search connector specified must also have a dynamic dropdown specified. This is because search connectors are meant to save the user from having to find and copy an ID value into a field - which the dynamic dropdown will handle for when the user wants to use the same ID every time.

Parent Key#

Ok, parent key is a little tricky, but it can be really helpful if you want to support line items (an array of sub-objects). When an action has one or more fields that have a parent key, we treat all those fields as the schema for building sub-objects, which we combine into a list and nest under the parent key.

For example, say you define two fields amount and quantity and give them both the parent key line_items. Now imagine a user has a trigger that provides this data:

{
    "sale": {
        "items_sold": [
          {
             "cost": "$3.00",
             "# sold": 12
          },
          {
             "cost": "$2.55",
             "# sold": 1
          }
        ]
    }
}

NOTE: The kind of data you receive ultimately depends on what the app's trigger providing the data returns. This means that if the app's trigger a customer's using doesn't provide line items, we'll transform arrays into CSV strings. There's really nothing you can do about this, but when testing, make sure the app you're using to test triggers supports line items.

The user could map cost into your amount field and # sold into the action's quantity field, like this:

parent key UI example

Zapier would produce this JSON for POSTing:

{
    "line_items": [
      {
         "amount": "$3.00",
         "quantity": 12
      },
      {
         "amount": "$2.55",
         "quantity": 1
      }
    ]
}

Zapier will automatically expand fields with the same parent_key into a nested list of objects according to how the source data comes in (we'll make as many objects inside the list as the original source). All you need to do is provide the same parent_key and expect an array of objects under that parent_key.

Send in POST by default#

If checked, we'll include the user-provided value in the POSTed JSON on the provided key (or nested key if double underscores __ are present).

If you utilize the pre_poll or ACTIONKEY_pre_poll methods via scripting you can get complete control over the JSON output beyond simple exclusion/inclusion.

List#

Indicates if this field can hold multiple values. For example, this could be useful if you want to allow users to add tags to a new contact, and you want them to be able to add more than one. List fields gain the +/- icons to the side.

list field example

↑ Was this documentation useful? Yes No
Get Help