Create custom workflow actions with the action builder (BETA)

• Speed up development by previewing how your action will display in HubSpot before writing any code.
• Reduce errors with a guided setup that outputs the correct JSON for workflow action schema files and makes API requests on your behalf.
• Streamline testing by ensuring your action looks and behaviors as expected before implementation.

• Create a developer account.
• If you plan to add the workflow action to an app built on the developer platform, create an app.

​

Use the builder

• In your app developer account, navigate to Apps.
• Click the app that you’d like to build the action for.
• In the left sidebar menu, click Workflows custom action builder.

• In the top right, click Import action definition.
• In the dialog box, enter your action definition.
• At the bottom, click Import. The editor will automatically be populated based on the action definition.

​

Add inputs

• To begin building your workflow action, click Add input or the + plus icon. These are the inputs that the action receives and will be filled by the user in-app when setting up the action.
• In the left panel, select an input field type for your action. Then, set up your input:
  • Field type: the field type for your input.
  • Label: the user-facing label for your input.
  • Key: the key the input’s data is returned under. This value must match your external API. For example, if your external API expects a user’s email address to be provided using the parameter name user_email, the key you specify in the workflow action builder must be user_email exactly, or the API cannot match the data sent.
  • Tooltip: add an information icon next to the label which displays the configured text within a tooltip.
  • Options: set up values for your input field. This field will appear if you’ve selected the Radio select, Dropdown select, or Multi-select field type options. You can manually set up static options, or use external data to populate your options.
  • Required field: determine if the input is required or not.
• After setting up your input, in the bottom, click Save. A preview of the input will appear in the right panel.
  
• To add another input, in the left sidebar menu, click the + plus icon.
• To add any dependencies to the input field, at the top, click the Dependencies tab.
• Click Add field dependencies. For example, you can choose to hide or grey out a field, based on the value of this field.
• Set up your field dependencies:
  • Choose which inputs should be dependent on this: select the other input fields that you want to be dependent on the field.
  • Choose what behavior you want to control: choose if this field controls the visibility or state of the field. For example, you can choose whether the field is hidden or greyed out.
  • Only show if the current field’s value is equal to: set the value to control the dependency.
• To add another dependency, click + Add input field dependency.
• To remove a dependency, click the delete icon next to the dependency group.

​

Add action details

• In the left sidebar menu, click the Action details icon.
• In the Basic info tab, set up your action details:
  • Display name: enter a name for your workflow action. This’ll appear when selecting and setting up the workflow action.
  • Available object types: select the CRM object types that this action can be used with. If an option isn’t selected, the action will appear in all workflow types.

• At the top, click the Action card tab. You can configure how the action card appears when selecting a workflow action from the editor.
• Enter a description for the workflow action card. You can review your action card in the section below.

​

Set up the API request triggered by your action

• In the left sidebar menu, click the API icon.
• In the Request panel tab, enter a Request URL for your workflow action.
  • This will be the URL where an HTTPS request is sent when the action is executed.
  • The request body will contain information about which user the action is executing on behalf of, and what values were entered for the input fields.
• To set up your API outputs, click the Outputs tab. These are values that the action will output that can be used by later actions in the workflow. An action can have zero, one, or many outputs.
• Click Add output. Then, set up your output:
  • Response key: the name of the parameter that your external API returns that can be used as an input in subsequent actions. For example, if the output from your external API includes a property named computed_output, you’d provide that property name for the Response key here.
  • Label: the user facing output label.
  • Data type: the field data type for your output.
• After setting up your output, at the bottom, click Save.

​

Manage inputs

• In the left sidebar menu, click the Inputs icon.
• To add additional information to your workflow action, click to toggle the Add additional info above inputs switch on.
• In the Additional info field, enter any additional information for your workflow action. For example, you can enter a brief description of what the action does, or any additional requirements or behavior that users should note when using the action.

​

Set up action logs

• In the left sidebar menu, click the Action logs icon.
• Click Add action log.
• Set up your action log:
  • Key: the unique identifier for this action log message.
  • Message: the message to show to users if the conditions for this action log are met.
  • Conditions: the action’s execution response determines which action log message to show. Choose what values should be present in the response object to show this log message.
• Enter a Key and Value for your condition.
• To delete a condition, click the delete icon.
• To add another condition for your action log, click + Add another condition.
• After setting up your action log, at the bottom, click Save.

​

Copy your workflow action code

• In the left sidebar menu, click the Action definition icon.
• Click Copy.
• You can then paste the code into your local custom workflow action schema file, or use it for making a POST request to the custom workflow actions API.

​

Publish your workflow action

• In the top right, click Publish action to either create a new action definition or update an existing action.
• In the dialog box, select from the following:
  • Create a new action definition: this will trigger a POST request on your behalf and automatically create a new action. If your app has been installed, the action will then appear in your available workflow actions in the workflow editor.
  • Patch an existing extension definition: this will trigger a PATCH request on your behalf and automatically update the specified existing action. If your app has been installed, the updated action will appear in your available workflow actions in the workflow editor. You can retrieve all action definitions for your app using the retrieve custom action definitions API.
• Click Create action definition or Patch existing definition.