Handling user configuration

You can set up a custom integration to be configurable.

When an integration is configurable, users can supply it with data during the installation flow. For example, the Auth0 integration lets users provide their Auth0 credentials.

The integration can then access this data throughout its lifecycle, such as when an action is executed.

After a user installs an integration, they can change its settings in the marketplace, via the integration's Configuration tab.

This topic explains how to set up an integration to be configurable.

Prerequisites

• You know how to create a manifest.json file.
• You're familiar with TypeScript.

Step 1: Set up the configurable options

In the manifest.json file, create an installation object that contains an array named configurationItems:

{
  "id": "431670d2-a642-4825-8e32-00aa432bf2ff",
  "name": "Hello World",
  "description": "A simple example of a custom integration.",
  "version": "0.1",
  "iconFile": "icon.png",
  "bannerFiles": [],
  "installation": {
    "configurationItems": []
  }
}

Then, for each configurable option that the integration supports, add an object to the array:

{
  "configurationItems": [
    {
      "key": "websiteName",
      "name": "Website Name",
      "description": "The name of Online Store website",
      "dataType": "string"
    }
  ]
}

Each object must have the following properties:

• key
• name
• description
• dataType

To learn more about these properties, see List of manifest.json options.

(Optional) Step 2: Validate the configuration

When a user attempts to configure an integration, either when adding the integration to a workspace or after the integration has already been added, the integration can check if the supplied data is valid. If it's not, the integration can prompt the user to provide valid data.

To learn more, see Validating user configuration.

Step 3: Access the configured data

You can access the user's configuration throughout an integration's lifecycle. For example, the following snippet demonstrates how to access the user's configuration via the Flow Action API and execute methods:

const myCustomAction = {
  getPossibleOutputs(designTimeContext) {
    console.log(designTimeContext.appConfigs);
  },

  execute(executionContext) {
    console.log(executionContext.appConfigs);
  },
};