Skip to main content

Configuration Wizard

The integrations that you build in the integration designer are meant to be reusable, and deployable across your hetrogenous customer base. To make this possible, you need to provide a way for your customers to configure your integrations to work with their specific environment.

When your customer configures and activates an instance of your integration, they'll walk through a configuration wizard where they'll authenticate with the third-party apps you're integrating with, and provide any other information that's needed to make the integration work. Some integrations have simple configuration wizards and might only require authentication to a third-party app, while others might involve multiple pages of configuration with dynamically generated dropdown menus, toggles, text fields and more.

This article covers how to build a configuration wizard for your integration that gives your customers a pleasent deployment experience.

Configuration wizard designer​

Customers enable and configure an instance of an integration through a Configuration Wizard. They work through Configuration Pages, authenticating with third-party apps and setting config variables.

Configuration pages can contain config variables of various types and helper text and images to prompt the user where to look. If your integration requires manual configuration of webhooks, the config wizard can also display the instance's webhook endpoints and API keys (see Endpoint API keys in the config wizard).

Displaying additional helper text in the configuration wizard​

To add helper text, including headings (H1 - H6) or paragraphs, click the + Text/Image button and select the type of text you'd like to add.

To add an image, your image will need to be publicly accessible online. Enter the public URL of the image you'd like shown on your config page.

For further customization, you can choose to add Raw HTML to your config page.

You an add a configuration page by clicking + Config Page, and you can rename a config page or add a short description to the page by clicking the pencil icon beside the page.

Displaying webhook information in the configuration wizard​

Your instance's webhook endpoints and API keys can be displayed in the configuration wizard. Click + Text/Image and then select Trigger Details as the Element Type. You can opt to show all flows' URLs, or the URL for a specific flow.

When your customers deploy an instance of your integration, they'll see the webhook information on the configuration page. This is handy if they need to manually configure webhooks in a third-party app.

Adding configuration variables​

You can define names, descriptions, variable types, and optional default values of config variables to your configuration wizard, and you'll reference the values that customers set for each in your integration.

When it comes time for your customer-facing teams to deploy your integration, they can enter or select configuration options and tailor the integration for a particular customer without the involvement of integration builders.

Config variables that you define in the config variable drawer can be used within your integration as inputs or steps, or through the Branch component to drive branching logic.

Config variable data types​

There are several types of configuration variables:

  • String is a standard string of characters
  • Date follows the form mm/dd/yyyy, and presents end users a calender widget to choose a date
  • Timestamp follows the form mm/dd/yyy, HH:MM [AM/PM], and presents end users a calendar and time widget to choose a date and time
  • Picklist allows you to define a series of options that your end user can choose from. Picklists are presented to end users as a dropdown menu of options. A picklist value can be up to 64 characters in length.
  • Code lets your end user enter JSON, XML, or other formatted code blocks. This is handy if customers have unique formats for recurring reports, or other formatted documents that differ from customer to customer. Choose a Code Language when you create the config variable for syntax highlighting.
  • Boolean allows your end user to choose either true or false.
  • Number allows your end user to enter a number (integer or decimal).
  • Object Selection allows your end user to select zero or more objects from a list. This config variable type always sources data from a data source.
  • Object Field Map allows your end user to map a series of fields. This config variable type always sources data from a data source.
  • JSON Form allows you to leverage JSON Forms to build your users' configuration experience. The code backing JSON Form config variables are developed in custom components and return objects that are made up of key/value pairs.
  • Connection is made up of multiple fields that determine how a component should connect to an external API. It might include a username, password, API key, endpoint URL, or several other things. Note that connection config variables can only be added to the first config page, as subsequent pages my use the connection to dynamically generate other config variables.
Inputs are sent to actions as strings

The type of config variable you choose affects the UI that the end user interacts with (they get toggles for booleans, date pickers for timestamps, an editor with syntax highlighting for code, etc). Regardless of what type of config variable you choose, though, all values are presented to actions as strings.

If you're writing a custom component, note that you will need to cast your action's input to the correct format. For example, you can JSON.parse() a JSON string, or run util.types.toNumber() or util.types.toBool() on a number or boolean input. You can use a clean function to simplify type casting.

Once you've added a config variable, you can use it as an inputs to actions within your integration.

List and key/value list config variables​

In addition to representing a single value, some config var types can represent a list of values, or a list of key/value pairs. This is helpful for when you want your users to be able to enter an unknown number of items as the values of a configuration variable. For example, you may want users to select one or more values from a picklist menu.

Config variables with a data type of string, date, timestamp, picklist, code, or boolean can be configured as lists or key/value lists.

To create a list config variable, create a new config variable and select LIST under Config Var Type:

When a list config variable is referenced by a step's input, that step's action receives a JavaScript array of values. The config variable in the example above would provide the array ["First Option", "Third Option", "Second Option"] to the action.

To create a key/value list config variable, create a new config variable and select KEY/VALUE LIST under Config Var Type:

When a key/value list config variable is referenced by a step's input, that step's action receives a JavaScript array of key/value pairs. The config variable in the example above would provide this array to the action:

[
  {
    key: "some-key",
    value: "Some value",
  },
  {
    key: "another-key",
    value: "Another value",
  },
];

Config variable data sources​

Data Sources allow you to populate a config variable dynamically after they enter some connection settings. This is handy because customers' configuration differs in third-party apps. Customers have different Facebook business names, different Google Analytics accounts, different fields on Salesforce resources, etc. You can pull in those things, and allow customers to choose their Slack channel, select a folder in Google Drive, map fields from Salesforce, etc.

If you would like to populate a config variable dynamically from a data source, first ensure that a connection config variable for the third-party app is present on your first config page. Those are generally automatically created when you add a step to your integration for that third-party. On a subsequent page, add your config variable. Under Data Source, select the component and data source that you would like to use (for example, the Slack Select Channel data source).

Your customers will authenticate with the third-party app on their first config page, and will see data dynamically loaded from the third-party populate the config variable.

JSON Forms config variables​

JSON Forms is a powerful form-generating tool that lets you transform JSON schema into a fillable form, and JSON Forms config variables are available on enterprise plans. You can build a static JSON form using the built-in JSON Forms component, or create dynamic configuration experiences by adding JSON Forms data sources to your custom components.

See the full JSON Forms article for more information.

Connection config variables​

Connections are a special type of config variable that contain the information necessary to connect to a third-party app. A connection might include a simple username and password pair, or might declare all the fields required for OAuth 2.0 (like auth URL, client ID, etc.).

You can read more about connections and OAuth 2.0 on the Connections article.

Config variable visibility​

By default, config variables that you add to your integration's configuration wizard are visible to customers who deploy instances of your integration. But, there are some situations where you may want to hide a config variable from the config wizard. For example:

  • All instances of your integration might share an API key to a third-party app. You may want to set that API key as a config variable, but not make it accessible or visible to your customer.
  • Your customer's instance need an API key to access your app, but you want to set it on their behalf as part of the instance deployment process. In that case, you want the customer user to be able to set it programmatically behind the scenes, but not see its value in the UI.

For each config variable that you add to your integration you can configure Permissions and Visibility. You have three options:

  • Customer is the default value. Customer users can view and edit the config variable, and it will always appear in the config wizard.
  • Embedded makes it so the config variable does not show up in the config wizard, but your app is able to set it programmatically through the embedded SDK. This is helpful if you want to set an API key for a user during the configuration process, but not allow the user to see or edit the value that is set.
  • Organization makes it so the config variable is not visible to your customer, and is not able to be set programmatically by your app. Config variables marked organization must have a default value, or else your team members will need to set the value on behalf of your customer.

Additionally, you can toggle the Visible to Organization toggle to false to hide the config variable from organization team members who open a customer's instance config wizard screen. The config variable is still available programmatically to organization members, but this prevents a sensitive config variable from being displayed unintentionally on an organization team member's screen.