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);
},
};
Updated 8 months ago