--- schema_version: "1" id: 2a3e93d04623336777dfdefca28ca3a3f48240c22b77f4b3152a0d9c3a8db7a2 title: Custom Activity Configuration collection: developer version: current locale: en-us portal_url: https://docs.salesforce.com/developer/current/en-us/marketing-cloud/guides/mc-app-development/custom-activity-config.md canonical_url: https://developer.salesforce.com/docs/marketing/marketing-cloud/guide/custom-activity-config.html source_site: developer.salesforce.com content_type: documentation content_hash: c88b09492518956d7ab912eea17216356328848b09a528b8f50d8801da85a746 products: - Marketing Cloud Engagement APIs and Programmatic Languages - Marketing Cloud --- # 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](https://developer.salesforce.com/docs/marketing/marketing-cloud/guide/creating-events.md). The config.json file includes the properties shown in this table. To view these properties in context, see the [sample config.json file](#sample-configjson-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](#metadata-object-properties) 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](#lang-object-properties) object | Required. An object that contains translation and localization information for the custom activity. For more information, see [Internationalize Branch Labels](https://developer.salesforce.com/docs/marketing/marketing-cloud/guide/internationalize-branch-labels.md). | | `arguments` | [arguments](#arguments-object-properties) object | Required. An object that contains arguments that are passed to the custom activity. | | `configurationArguments` | [configurationArguments](#configurationarguments-object-properties) object | Required. An object that contains information that relates to this instance of the activity. | | `userInterfaces` | [userInterfaces](#userinterfaces-object-properties) object | Required. An object that contains endpoints and UI configurations for the activity’s user interfaces. | | `wizardSteps` | [wizardSteps](#wizardsteps-array-properties) array | An array of objects that define the steps that the user navigates through when configuring the custom activity. | | `schema` | [schema](#schema-object-properties) object | An object that mirrors the activity configuration from the top level of the config.json file. | | `copySettings` | [copySettings](#copysettings-object-properties) object | An object that defines rules for copying the configuration. | ## metaData Object Properties | 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](#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. | ### Custom Activity Icon Details 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 ## lang Object Properties 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. | ## arguments Object Properties | 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. | ## configurationArguments Object Properties | Property | Data Type | Description | | ------------------------- | ---------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- | | `applicationExtensionKey` | String | Required. An object that contains information that relates to this instance of the activity. | | `publish` | [configurationArgumentActivity](#configurationargumentactivity-object-properties) Object | An object that defines the actions taken when a user publishes a journey that contains the custom activity. | | `save` | [configurationArgumentActivity](#configurationargumentactivity-object-properties) Object | An object that defines the actions taken when a user saves a journey that contains the custom activity. | | `unpublish` | [configurationArgumentActivity](#configurationargumentactivity-object-properties) Object | An object that defines the actions taken when a user unpublishes a journey that contains the custom activity. | | `validate` | [configurationArgumentActivity](#configurationargumentactivity-object-properties) Object | An object that defines the actions taken when a user validates a journey that contains the custom activity. | | `stop` | [configurationArgumentActivity](#configurationargumentactivity-object-properties) Object | An object that defines the actions taken when a user stops a journey that contains the custom activity. | ## configurationArgumentActivity Object Properties 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` | String | An object that contains additional keys and values to add to the request body. Specify this property as an escaped JSON string. | | `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](https://developer.salesforce.com/docs/marketing/marketing-cloud/guide/encode-custom-activities-using-jwt.md). | | `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](https://developer.salesforce.com/docs/marketing/marketing-cloud/guide/secure-custom-activity-using-oauth.md). | | `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. | ## userInterfaces Object Properties 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`. | ## wizardSteps Array Properties 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. ![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.](https://developer.salesforce.com/docs/media/images/journey-custom-activity-wizardsteps.png) ## schema Object Properties The schema object specifies schema information about in and out arguments. The schema object has the structure shown in this example. ```js "schema": { "arguments": { "execute": { "inArguments": [ "{inArgumentName}": { "dataType": "{dataType}", "isNullable": {true|false}, "direction": "in", "access": "{visible|hidden}" } ], "outArguments": [ "{outArgumentName}": { "dataType": "{dataType}", "isNullable": {true|false}, "direction": "out", "access": "{visible|hidden}" } ] } } } ``` 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. ## copySettings Object Properties 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. | ## Sample config.json File ```json { "workflowApiVersion": "1.1", "name": "Custom Activity Name", "description": "Custom Activity Description", "metaData": { "icon": "images/icon.svg", "category": "Custom" }, "type": "REST", "lang": { "en-US": { "name": "Localized Custom Activity Name", "description": "Localized Custom Activity Description", "label1": "Localized Step 1", "label2": "Localized Step 2", "label3": "Localized Step 3" } }, "arguments": { "execute": { "inArguments": [ { "staticValue": 0, "databoundEmailAddress": "{{Event.EventKey.EmailAddress}}" } ], "outArguments": [ { "returnValue": "default" } ], "timeout": 10000, "retryCount": 1, "retryDelay": 1000, "concurrentRequests": 6, "url": "https://example.com/execute", "securityOptions": { "securityType": "securityContext", "securityContextKey": "EXTERNAL_KEY" } } }, "configurationArguments": { "save": { "url": "https://example.com/save", "securityOptions": { "securityType": "securityContext", "securityContextKey": "EXTERNAL_KEY" } }, "publish": { "url": "https://example.com/publish", "securityOptions": { "securityType": "securityContext", "securityContextKey": "EXTERNAL_KEY" } }, "validate": { "url": "https://example.com/validate", "securityOptions": { "securityType": "securityContext", "securityContextKey": "EXTERNAL_KEY" } }, "stop": { "url": "https://example.com/stop", "securityOptions": { "securityType": "securityContext", "securityContextKey": "EXTERNAL_KEY" } } }, "wizardSteps": [ { "label": "label1", "key": "step1" }, { "label": "label2", "key": "step2" }, { "label": "label3", "key": "step3", "active": false } ], "userInterfaces": { "configModal": { "fullscreen": true, "url": "configModal.html" }, "runningModal": { "url": "runningModal.html" }, "runningHover": { "url": "runningHover.html" } }, "schema": { "arguments": { "execute": { "inArguments": [ { "staticValue": { "dataType": "Number", "isNullable": false, "direction": "in" }, "databoundEmailAddress": { "dataType": "Email", "isNullable": false, "direction": "in" } } ], "outArguments": [ { "returnValue": { "dataType": "Text", "isNullable": false, "direction": "out" } } ] } } }, "copySettings": { "allowCopy": true, "ignoreArguments": ["eventDefinitionKey"] } } ```