Configuration Variables

Overview

Configuration variables are key-value pairs that can be referenced by instances of integrations. Config variables are used to store commonly referenced strings, like a Slack webhook URL or a customer's UUID. You can create organization-wide config variables, or they can be set for specific customers or integrations. When an instance of an integration is deployed, you copy organization, customer, or default integration config variable values into the deployment.

To store credentials (usernames, passwords, API keys, etc.) please use the authorization credential store instead.

For a quickstart on using configuration variables in an integration, click here.

Should I Use Organization, Customer, or Integration-specific Configuration Variables?

Configuration variables that are set at the organization level should be generic to all customers, and referenced by multiple integrations. For example, if you have multiple integrations that save completed orders to a common S3 bucket, that bucket name could be saved as an organization-level config variable.

Configuration variables that are set at the customer level should be specific to the customer. For example, one or more integrations might need to reference a customer's external UUID. Each customer could have a config variable customerUUID set, and instances of integrations would be configured to reference configVars.customerUUID, which would be different for each instance based on the customer the instance was deployed to.

Configuration variables can also be set at the integration level, and should be generic to all customers, integration-specific, and referred to by multiple steps of the integration. For example, if multiple steps of an integration reference an API endpoint, that endpoint could be saved as an integration-specific config variable. If you need to change the API endpoint later, you would only need to change a single integration-specific variable.

Organization Configuration Variables

To manage configuration variables at the organization level, click Settings on the left-hand sidebar, and then click the Config Variables tab.

You can delete a config variable by clicking the icon, or add a new config variable by clicking the + ADD CONFIG VARIABLE button.

If you have a more complex config variable value that you would like to enter, like a section of HTML, JSON object, or XML block, click the icon to the right of a config var to open a code editor.

Modifying existing config variables can be done by returning to this screen and modifying values. Modified values are not deployed automatically to existing instances unless an instance is reconfigured and redeployed to use the new values.

Customer Configuration Variables

To manage configuration variables at the customer level, click Customers on the left-hand sidebar, select the customer you want to manage, and then click the customer's Config Variables tab.

You can delete a config variable by clicking the icon, or add a new config variable by clicking the + ADD CONFIG VARIABLE button.

If you have a more complex config variable value that you would like to enter, like a section of HTML, JSON object, or XML block, click the icon to the right of a config var to open a code editor.

Modifying existing config variables can be done by returning to this screen and modifying values. Modified values are not deployed automatically to existing instances unless an instance is reconfigured and redeployed to use the new values.

Required Configuration Variables for an Integration

In order for an integration to reference configuration variables as inputs for steps, you must first enumerate the keys of the config variables your integration will require.

Within the integration designer click the Required Config Variables tab. Variables can be given integration-specific default values here, or defaults can be left blank if you plan to copy config variable values from the organization or customer.

Like config vars set at the organization or customer level, you can click the icon to enter more complex config var values, like JSON objects, HTML, or XML.

Referencing Configuration Variables in an Integration

A configuration variable can be used as an input of an integration step by referencing configVars.VARIABLE_NAME.

Multiple variables and strings can even be strung together as input using JSONata syntax.

For example, suppose you have two configuration variables, myEndpoint (set at the organization level) and customerUUID (set at the customer level), and you would like to make a RESTful call to a URL made up of those two variables. You can concatenate those configuration variables into a cohesive URL using JSONata syntax:

=configVars.customerURL & "?customer=" & configVars.customerUUID

For More Information: Component Input

Testing Configuration Variables

You can set values for configuration variables to use as you test and debug your integration. Set those values in the lower right-hand Testing pane of the integration designer screen. You can either select a default value from the dropdown, or choose a config variable value set at the organization level. If you would like to add an organization level configuration variable, you can click +Organization Variable.

The values you use to test an integration will not be published with your integration or copied to instances of your integration.

For More Information: Integration Designer

Assigning Configuration Variable Values When Creating Instances

When an instance of an integration is created, required configuration variables need to be assigned values before you can deploy the instance. For each required configuration variable, click the dropdown menu and select the default instance variable value, or a configuration variable≈ value saved at the organization or customer level.

If you would like create new configuration variables at the customer or organization level, click the + Customer Variable or + Organization Variable buttons. Variables set in this way will be saved to the customer or organization's config variable store.

For More Information: Instance Config Vars

Last updated on