Custom Activity Configuration
In Journey Builder, both custom events and custom activities follow the same structure. For more information about creating custom events, see Considerations for Building Custom Events.
The config.json file includes the properties shown in this table. To view these properties in context, see the sample config.json file.
| Property | Data Type | Description |
|---|---|---|
workflowApiVersion | String | Required. The version of the workflow API to use for the custom activity. Accepted values are 1.1, 1.0, and 0.5. We recommend that you use the latest version unless it’s necessary to use an older version. |
metaData | metaData object | Required. An object that contains values that identify and categorize each custom activity. |
type | String | Required. The type of activity. There are two standard activity types.
|
lang | lang object | Required. An object that contains translation and localization information for the custom activity. For more information, see Internationalize Branch Labels. |
arguments | arguments object | Required. An object that contains arguments that are passed to the custom activity. |
configurationArguments | configurationArguments object | Required. An object that contains information that relates to this instance of the activity. |
userInterfaces | userInterfaces object | Required. An object that contains endpoints and UI configurations for the activity’s user interfaces. |
wizardSteps | wizardSteps array | An array of objects that define the steps that the user navigates through when configuring the custom activity. |
schema | schema object | An object that mirrors the activity configuration from the top level of the config.json file. |
copySettings | copySettings object | An object that defines rules for copying the configuration. |
| Property | Data Type | Description |
|---|---|---|
icon | String | The path to an icon that is shown when a user adds the activity to the journey canvas. For more information, see Custom Activity Icon Details. |
category | String | Required. The category type of the custom activity. Accepted values are message, customer, flow, and custom. If the request includes an invalid or missing category value, the activity is added to the custom category. This value overrides the category selected in the installed package. |
expressionBuilderPrefix | String | A string prefix in the expression builder for decision split. The default value is Custom Activity. |
isConfigured | Boolean | If the value of this property is true, the activity is marked as configured when a user adds it to the canvas. |
configurationDisabled | Boolean | If this value is true and metaData.isConfigured is also true, the activity configuration button is disabled. |
configOnDrop | Boolean | If this value is true, the activity configuration opens when a user adds the activity to the canvas. |
The value of the icon property must be a path to an icon. The path can be an absolute URL or a path that’s relative to the URL of the custom activity.
If you don’t specify a value for the icon property, Journey Builder checks to see if a file called icon.png exists in the path that you specified for the custom activity. If that file doesn’t exist, it looks for a file called icon.svg in the same path. If that file doesn’t exist, Journey Builder uses a default icon.
Journey Builder always uses the icon value in the version of the config.json file hosted on your web server. If you add a custom activity to your journey, and then modify the configuration of that instance of the custom activity, Journey Builder doesn’t update the icon. If you change the value of the icon property in the config.json hosted on your web server, the icon is updated for all instances of that custom activity in the journey.
If you change the value of icon in the config.json served by your webserver, the icon is updated for all instances of that custom activity in the journey.
The icon file must meet these specifications.
- Supported file formats: .png, .svg, .jpg, .gif
- Maximum width and height: 40 pixels × 40 pixels
- File size limit: None
The lang object contains at least one object. The name of each object must equal the name of a BCP 47 locale code, such as en-US for US English or pt-BR for Brazilian Portuguese. In each object, you specify the name and description of the custom activity for the specified locale.
| Property | Data Type | Description |
|---|---|---|
{localeCode} | Object | An object that contains the name and description of the custom activity in the specified locale. The name of the object must be a BCP 47 locale code such as en-US. |
{localeCode}.name | String | The name of the custom activity in the language of the specified locale. |
{localeCode}.description | String | A description of the custom activity in the language of the specified locale. |
{localeCode}.{key} | String | A custom label referenced in the activity. If a label in the activity matches this key, a user whose settings use this language sees this value instead of the default value. |
| Property | Data Type | Description |
|---|---|---|
execute | Object | An object that contains information that is sent to and returned by the activity each time a contact enters it. |
execute.inArguments | Array of objects | An object array that defines the data that Journey Builder passes to your execute endpoint when a contact enters the custom journey activity. |
execute.outArguments | Array of objects | An object array that defines the fields that your application returns in response to requests from Journey Builder. |
execute.timeout | Integer | The amount of time in milliseconds before requests to the custom activity endpoint time out. The minimum value is 1000 and the maximum value is 100000. The default value is 20000. |
execute.retryCount | Integer | The number of times to retry the call to the custom activity endpoint if it times out. The minimum value is 0 and the maximum value 5. The default value is 0. |
execute.retryDelay | Integer | The amount of time in milliseconds to wait for a response from the custom activity endpoint before retrying it. The minimum value is 0 and the maximum value is 10000. The default value is 1000. |
execute.concurrentRequests | Integer | The number of times the activity can run in parallel. The minimum value is 1 and the maximum value is 10. The default value is 6. Before you use concurrent requests, test the ability of the target application to handle multiple loads. If you observe gateway errors or timeouts, consider increasing the retry and timeout values. |
execute.url | String | The application endpoint for the activity. |
| Property | Data Type | Description |
|---|---|---|
applicationExtensionKey | String | Required. An object that contains information that relates to this instance of the activity. |
publish | configurationArgumentActivity Object | An object that defines the actions taken when a user publishes a journey that contains the custom activity. |
save | configurationArgumentActivity Object | An object that defines the actions taken when a user saves a journey that contains the custom activity. |
unpublish | configurationArgumentActivity Object | An object that defines the actions taken when a user unpublishes a journey that contains the custom activity. |
validate | configurationArgumentActivity Object | An object that defines the actions taken when a user validates a journey that contains the custom activity. |
stop | configurationArgumentActivity Object | An object that defines the actions taken when a user stops a journey that contains the custom activity. |
Each of the actions in the configurationArguments object (publish, unpublish, save, validate, and stop) can contain the properties in this table.
| Property | Data Type | Description |
|---|---|---|
url | String | The HTTPS endpoint that receives an HTTP POST request when a user performs the action. |
body | Object | An object that contains additional keys and values to add to the request body. |
headers | Object | An object that contains additional keys and values to add to the request headers. |
useJwt | Boolean | If true, requests to the endpoint are encoded as a JWT. For more information, see Encode Custom Activities Using a JWT. |
customerKey | String | The identifier of an external key to use to encode a JWT. |
securityOptions | Object | An object that contains information about OAuth 2.0 bearer tokens. For more information, see Secure a Custom Activity Using an OAuth 2.0 Bearer Token. |
securityOptions.securityType | String | The type of key to use to obtain the bearer token. Specify securityContext for this property. |
securityOptions.securityContextKey | String | The name of an external key that is used in the key exchange. |
The userInterfaces object contains information about the appearance of the configuration page for the custom activity in the journeys user interface.
| Property | Data Type | Description |
|---|---|---|
configModal | Object | Required. An object that is used to configure the journey activity. |
configModal.url | String | The URL of the UI that users see when they configure this activity. The default value is index.html. |
configModal.height | Integer | The height in pixels of the iframe that contains the configuration interface for the custom activity. |
configModal.width | Integer | The width in pixels of the iframe that contains the configuration interface for the custom activity. |
configModal.fullscreen | Boolean | Specifies whether to show the configuration interface in full screen mode. If true, the configuration UI fills the entire screen, even when values are defined for height and width. The default value is false. |
The wizardSteps array contains objects that define the steps that the user navigates through as they configure the custom activity. Each object contains the values in this table.
| Property | Data Type | Description |
|---|---|---|
label | String | The name to display for this step in the user interface. |
key | String | A unique key to identify the step. |
active | Boolean | Determines whether to show the step in the configuration flow. If this value is true, the step is shown in the configuration flow. The default value is true. |
This image shows a configuration page for a custom journey activity in fullscreen mode. The three numbered tabs ("Workflow", "Execute", and "Editor") correspond to the label values in the wizardSteps object.
The schema object specifies schema information about in and out arguments. The schema object has the structure shown in this example.
The inArguments and outArguments arrays contain objects that specify the characteristics of each argument.
The context of the call determines the direction of the arguments in the schema. The values that you provide must match the execution context.
The outArguments can’t contain null values.
If the value of the access property parameter is set to hidden or isn’t specified, the argument isn’t shown in subsequent expression builders.
These are the properties of the copySettings object.
| Property | Data Type | Description |
|---|---|---|
allowCopy | Boolean | Determines whether the configuration can be copied. If the value is true, the configuration can be copied. |
ignoreArguments | Array | Each item in the array corresponds to a property that isn't copied with the rest of the configuration. |