Sometimes, API endpoints require clients to specify a parent object in order to create or access the child resources. For instance, specifying a spreadsheet id in order to retrieve its worksheets. Since people don’t speak in auto-incremented ID’s, it is necessary that Zapier offer a simple way to select that parent using human readable handles.

Our solution is to present users a dropdown that is populated by making a live API call to fetch a list of parent objects. We call these special dropdowns “dynamic dropdowns.”

​
Definition

To define one you include the dynamic property on the inputFields object. The value for the property is a dot-separated string concatenation.

//...
issue: {
  key: 'issue',
  //...
  create: {
    //...
    operation: {
      inputFields: [
        {
          key: 'project_id',
          required: true,
          label: 'This is a dynamic dropdown',
          dynamic: 'project.id.name'
        }, // will call the trigger with a key of project
        {
          key: 'title',
          required: true,
          label: 'Title',
          helpText: 'What is the name of the issue?'
        }
      ]
    }
  }
}

The dot-separated string concatenation follows this pattern:

  • The key of the trigger you want to use to power the dropdown. required
  • The value to be made available in bundle.inputData. required
  • The human friendly value to be shown on the left of the dropdown in bold. optional

In the above code example the dynamic property makes reference to a trigger with a key of project. Assuming the project trigger returns an array of objects and each object contains an id and name key, i.e.

[
  { id: "1", name: "First Option", dateCreated: "01/01/2000" },
  { id: "2", name: "Second Option", dateCreated: "01/01/2000" },
  { id: "3", name: "Third Option", dateCreated: "01/01/2000" },
  { id: "4", name: "Fourth Option", dateCreated: "01/01/2000" },
];

The dynamic dropdown would look something like this.

​
Use a resource

In the first code example the dynamic dropdown is powered by a trigger. You can also use a resource to power a dynamic dropdown. To do this combine the resource key and the resource method using camel case.

index.js
const App = {
  // ...
  resources: {
    project: {
      key: "project",
      // ...
      list: {
        // ...
        operation: {
          perform: () => {
            return [{ id: 123, name: "Project 1" }];
          }, // called for project_id dropdown
        },
      },
    },
    issue: {
      key: "issue",
      // ...
      create: {
        // ...
        operation: {
          inputFields: [
            {
              key: "project_id",
              required: true,
              label: "Project",
              dynamic: "projectList.id.name",
            }, // calls project.list
            {
              key: "title",
              required: true,
              label: "Title",
              helpText: "What is the name of the issue?",
            },
          ],
        },
      },
    },
  },
};

​
Hide the trigger

In some cases you will need to power a dynamic dropdown but do not want to make the Trigger available to the end user. Here it is best practice to create the trigger and set hidden: true on it’s display object.

const App = {
  // ...
  triggers: {
    new_project: {
      key: "project",
      noun: "Project",
      // `display` controls the presentation in the Zapier Editor
      display: {
        label: "New Project",
        description: "Triggers when a new project is added.",
        hidden: true,
      },
      operation: {
        perform: projectListRequest,
      },
    },
    another_trigger: {
      // Another trigger definition...
    },
  },
};

​
Dependencies between dropdowns

You can have multiple dynamic dropdowns in a single Trigger or Action. And a dynamic dropdown can depend on the value chosen in another dynamic dropdown when making it’s API call. Such as a Spreadsheet and Worksheet dynamic dropdown in a trigger or action. This means you must make sure that the key of the first dynamic dropdown is the same as referenced in the trigger powering the second.

Let’s say you have a Worksheet trigger with a perform method similar to this.

perform: async (z, bundle) => {
  const response = await z.request("https://example.com/api/v2/projects.json", {
    params: {
      spreadsheet_id: bundle.inputData.spreadsheet_id,
    },
  });

  // response.throwForStatus() if you're using core v9 or older

  return response.data; // or response.json if you're using core v9 or older
};

And your New Records trigger has a Spreadsheet and a Worksheet dynamic dropdown. The Spreadsheet dynamic dropdown must have a key of spreadsheet_id. When the user selects a spreadsheet via the dynamic dropdown the value chosen is made available in bundle.inputData. It will then be passed to the Worksheet trigger when the user clicks on the Worksheet dynamic dropdown.

const App = {
  // ...
  triggers: {
    // ...
    issue: {
      key: "new_records",
      // ...
      operation: {
        inputFields: [
          {
            key: "spreadsheet_id",
            required: true,
            label: "Spreadsheet",
            dynamic: "spreadsheet.id.name",
          },
          {
            key: "worksheet_id",
            required: true,
            label: "Worksheet",
            dynamic: "worksheet.id.name",
          },
        ],
      },
    },
  },
};

The Google Sheets integration is an example of this pattern.

Note: Even if a trigger to power a dynamic dropdown is hidden for direct use, you still need to define the input fields, and whether these are required. In the above example, when the Worksheet trigger defines a required spreadsheet_id field (which also needs to be a dynamic dropdown), products such as the editor will use this in two ways. Firstly, the worksheet field will be disabled until the spreadsheet field has been set. Secondly, when the user changes the spreadsheet field, the worksheet field gets cleared.

​
Detect when a trigger is used for a dynamic dropdown

If you want your trigger to perform specific scripting for a dynamic dropdown you will need to make use of bundle.meta.isFillingDynamicDropdown. This can be useful if need to make use of pagination in the dynamic dropdown to load more options.

const App = {
  // ...
  resources: {
    project: {
      key: "project",
      // ...
      list: {
        // ...
        operation: {
          canPaginate: true,
          perform: () => {
            if (bundle.meta.isFillingDynamicDropdown) {
              // perform pagination request here
            } else {
              return [{ id: 123, name: "Project 1" }];
            }
          },
        },
      },
    },
    issue: {
      key: "issue",
      // ...
      create: {
        // ...
        operation: {
          inputFields: [
            {
              key: "project_id",
              required: true,
              label: "Project",
              dynamic: "projectList.id.name",
            }, // calls project.list
            {
              key: "title",
              required: true,
              label: "Title",
              helpText: "What is the name of the issue?",
            },
          ],
        },
      },
    },
  },
};

This feature makes it easier for users to handle the following scenario in a workflow that has multiple steps:

  • The value for the input field depends on an output field from an earlier step.
  • The value of that output field cannot be used directly.
  • They need an additional search step that takes the output they cannot use directly, and translate it into something they can.

Example: Let’s say the input field takes the ID of a lead. The user could select a lead from the dynamic dropdown, but then the workflow would act on the same lead every time it runs. An earlier step returns the email address of the lead, but not their ID. The user will need to prepend a search-step that takes the email address and returns the ID.

Users can do this themselves, but by using this feature, Zapier products can make this task easier.

​
How it works for the user

In the Zap editor for example, dynamic dropdowns that use this feature will display a button next to the dynamic dropdown. When the user clicks the button, the right search step is automatically prepended, and correct output field mapped into the dynamic dropdown.

​
How to configure it

In the definition of the input field, configure search with a value of <searchActionKey>.<outputFieldKey>.

  • Replace <searchActionKey> with the key of the search action that should prepeded to the user’s workflow.
  • Replace <outputFieldKey> with the key of the output field from that search action that should be mapped as value for the input field.

Here’s an example:

{
    key: 'project_id',
    required: true,
    label: 'Project',
    dynamic: 'list_projects.id.name',
    search: 'search_projects.id',
}
Field typesPlatform CLI tutorial