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.

PropertyData TypeDescription
workflowApiVersionStringRequired. 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.
metaDatametaData objectRequired. An object that contains values that identify and categorize each custom activity.
typeStringRequired. The type of activity. There are two standard activity types.
  • Rest
  • RestDecision
langlang objectRequired. An object that contains translation and localization information for the custom activity. For more information, see Internationalize Branch Labels.
argumentsarguments objectRequired. An object that contains arguments that are passed to the custom activity.
configurationArgumentsconfigurationArguments objectRequired. An object that contains information that relates to this instance of the activity.
userInterfacesuserInterfaces objectRequired. An object that contains endpoints and UI configurations for the activity’s user interfaces.
wizardStepswizardSteps arrayAn array of objects that define the steps that the user navigates through when configuring the custom activity.
schemaschema objectAn object that mirrors the activity configuration from the top level of the config.json file.
PropertyData TypeDescription
iconStringThe 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.
categoryStringRequired. 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.
expressionBuilderPrefixStringA string prefix in the expression builder for decision split. The default value is Custom Activity.
isConfiguredBooleanIf the value of this property is true, the activity is marked as configured when a user adds it to the canvas.
configurationDisabledBooleanIf this value is true and metaData.isConfigured is also true, the activity configuration button is disabled.
configOnDropBooleanIf 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.

PropertyData TypeDescription
{localeCode}ObjectAn 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}.nameStringThe name of the custom activity in the language of the specified locale.
{localeCode}.descriptionStringA description of the custom activity in the language of the specified locale.
{localeCode}.{key}StringA 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.
PropertyData TypeDescription
executeObjectAn object that contains information that is sent to and returned by the activity each time a contact enters it.
execute.inArgumentsArray of objectsAn object array that defines the data that Journey Builder passes to your execute endpoint when a contact enters the custom journey activity.
execute.outArgumentsArray of objectsAn object array that defines the fields that your application returns in response to requests from Journey Builder.
execute.timeoutIntegerThe 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.retryCountIntegerThe 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.retryDelayIntegerThe 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.concurrentRequestsIntegerThe 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.urlStringThe application endpoint for the activity.
PropertyData TypeDescription
applicationExtensionKeyStringRequired. An object that contains information that relates to this instance of the activity.
publishconfigurationArgumentActivity ObjectAn object that defines the actions taken when a user publishes a journey that contains the custom activity.
saveconfigurationArgumentActivity ObjectAn object that defines the actions taken when a user saves a journey that contains the custom activity.
unpublishconfigurationArgumentActivity ObjectAn object that defines the actions taken when a user unpublishes a journey that contains the custom activity.
validateconfigurationArgumentActivity ObjectAn object that defines the actions taken when a user validates a journey that contains the custom activity.
stopconfigurationArgumentActivity ObjectAn 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.

PropertyData TypeDescription
urlStringThe HTTPS endpoint that receives an HTTP POST request when a user performs the action.
bodyObjectAn object that contains additional keys and values to add to the request body.
headersObjectAn object that contains additional keys and values to add to the request headers.
useJwtBooleanIf true, requests to the endpoint are encoded as a JWT. For more information, see Encode Custom Activities Using a JWT.
customerKeyStringThe identifier of an external key to use to encode a JWT.
securityOptionsObjectAn 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.securityTypeStringThe type of key to use to obtain the bearer token. Specify securityContext for this property.
securityOptions.securityContextKeyStringThe 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.

PropertyData TypeDescription
configModalObjectRequired. An object that is used to configure the journey activity.
configModal.urlStringThe URL of the UI that users see when they configure this activity. The default value is index.html.
configModal.heightIntegerThe height in pixels of the iframe that contains the configuration interface for the custom activity.
configModal.widthIntegerThe width in pixels of the iframe that contains the configuration interface for the custom activity.
configModal.fullscreenBooleanSpecifies 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.

PropertyData TypeDescription
labelStringThe name to display for this step in the user interface.
keyStringA unique key to identify the step.
activeBooleanDetermines 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.

A screenshot of a custom journey activity configuration page. The name of the activity, My Custom Activity, appears at the top of the configuration page. Under the activity name are three tabs, labeled Workflow, Execute, and Editor.

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.