Marketing Cloud Package Development

Marketing Cloud Packages
Installed Package Types
Create and Install Packages
API Integration
Create a Marketing Cloud App
Extend Journey Builder
Build Custom Activities and Events
Create Custom Activity UI
Create Custom Activity Configuration
Postmonger Events Reference
Define a Custom Split Activity with Multiple Outcomes
Internationalize Branch Labels
Load Custom UI for Your Activity
Support Undo and Redo
Icon Specifications
Encode Custom Activities Using a JWT
JWT: Encode with Customer Key
Encode with JWT Signing Secret
Troubleshoot Custom Activities
Register Endpoint for a Custom Component
Example Rest Activity
Considerations for Building Custom Events
Extend Content Builder
List Your App in AppExchange

Custom Activity Configuration

For simplicity, the documentation mostly refers to custom activities. In Journey Builder, custom events and custom activities use the same framework, so building either object follows the same structure. For event-specific instructions, see Considerations for Building Custom Activities.

config.json Definition Structure

config.json JSON Parameters

Property Data Type Required Description
workflowApiVersion String Yes Property that tells Journey Builder which version this custom activity uses. Use the latest version where possible, though the API provides backwards compatibility. Accepted values are 1.1, 1.0, and 0.5.
metaData Object Yes Object containing UI-only values that help you identify and categorize each custom activity. Third-party sources pass more properties as applicable.
  • icon - String representing the icon for this activity. Displays what is in metaData.icon in config.json. If not provided, Journey Builder looks for /icon.svg at the root of the endpoint URL. If icon.svg doesn’t exist, it looks for /icon.png. If /icon.png doesn’t exist, a default icon is displayed.
  • category - String representing the type of activity. This value must include one of the Marketing Cloud-provided activity category types:
    • message
    • customer
    • flow
    If the call includes an invalid or missing category value, the activity falls under the 'Custom' category. This value overrides the category selected in the installed package.
  • expressionBuilderPrefix - Use this field to assign custom activities a pre-determined string prefix in the expression builder for decision split. Defaults to Custom Activity if not provided. Pass this field in through the config.json file or include it in the custom activity payload.

    The prefix allows you to easily identify and categorize custom activities. For example, the prefix for Sales Cloud activities could be the object configured for a given activity.

  • isConfigured - Optional boolean value. If true, the activity is marked as configured when it is dropped on the canvas.
  • configurationDisabled - Optional boolean value. If true and metaData.isConfigured is also true, the activity configuration button is disabled.
  • configOnDrop - Optional boolean value. If true, the activity configuration opens when the activity is dropped on the canvas.
type String Yes String property representing the type of activity. This value must include one of the Marketing Cloud types or match a valid defined custom C# activity. Valid Marketing Cloud value types include:
  • MultiCriteriaDecision
  • DataExtensionUpdate
  • EMAILV2
  • EngagementDecision
  • randomSplit
  • Wait
  • Rest
lang String Yes Used to define i18n strings. Each entry must match a Marketing Cloud-supported internationalization code, based on two-letter ISO 639-1 standard. Examples: en-US for American English, pt-BR for Portuguese Brazilian, and so on. See the Internationalize Branch Labels section in Go Further with Custom Activities.
  • name - Name the activity something descriptive, such as Send an Email, Send a Text, or Create Salesforce Lead, that displays in the activity list on the Journey Builder canvas. For simplicity, give the activity the same name you used when registered the endpoint in the installed package in Marketing Cloud.
  • description - Description of the activity.
arguments Object Yes Contains information sent to the activity each time it executes. See Data Binding for more information on formulating inArguments and outArguments.
  • execute - The API calls this method for each contact processed by the journey.
  • execute.inArguments - Any static or data bound value configured for the activity. By default, the config.json file sets these arguments. Or you can add inArguments at configuration time.
  • execute.outArguments - Key and value pair for each field expected in the response body of the request
  • execute.timeout - How long, in milliseconds, before each rest activity in the journey times out. Must be from 1,000 to 100,000 milliseconds. Default is 60,000 milliseconds.
  • execute.retryCount - How many times to retry each rest activity in the journey after the rest activity times out. Must be from 0 to 5. Default is 0.
  • execute.retryDelay - How long, in milliseconds, to wait before each rest activity in the journey is retried. Must be from 0 to 10,000 milliseconds. Default is 1,000 milliseconds.
  • execute.concurrentRequests - How many rest activities to run in parallel. Must be from 1 to 10. Default is 1, which means no concurrent requests. Before you use concurrent requests, test the scalability and performance of the target site. If you observe increased gateway errors or timeouts, consider adding retry and increasing the timeout value. Contact your Marketing Cloud account representative to enable concurrent requests.
  • execute.url - Endpoint used to execute the journey
configurationArguments Object Yes Object containing information that relates to this instance of the activity. All configuration arguments except publish are optional.
  • applicationExtensionKey - This read-only value is auto-assigned to custom Journey Builder activities and events when they are created and is called Unique Key in Marketing Cloud Setup. Journey Builder overrides the applicationExtensionKey in the config.json if it is incorrect, so we recommend leaving it out.
  • save - Endpoint that receives a notification when a user saves the journey.
  • publish - Endpoint that receives a notification when a user publishes the journey.
  • unpublish - Endpoint that receives a notification when a user unpublishes the journey.
  • validate - Endpoint that receives a notification when a user performs some validation as part of the publishing process.
  • stop - Endpoint that receives a notification when a user stops any active version of the journey. The notification is for that particular version.
  • TestSave - Endpoint that receives a notification when a user saves the journey and publishes while in Test Mode. Unless this configurationArgument is included, notifications do not send to endpoints when a journey is published in Test Mode.
wizardSteps Array No Contains an array of objects that define the steps that the user navigates through when configuring the custom activity. Each object follows this format:
{ "label": "Step 1", "key": "step1", "active": true }
  • label - The text displayed in the wizard at the top of the configuration screen. This value uses internationalized text when associated with the i18n key defined in the config.json's lang object.
  • key - A unique identifier for the step. customActivity.js uses this key to determine what step to show when the user navigates to a new step.
  • active - Determines whether to show the step in the configuration flow. This setting defaults to true.
userInterfaces Object Yes Contains endpoints and UI configurations for the activity's user interfaces: the configuration modal, running mode hover, and running mode details modal.
  • configModal - Required UI object used to configure the activity. See the Load Custom UI for Activities on Running Journeys section in Go Further with Custom Activities for an example.
  • configModal.url - Endpoint for the UI displayed to marketers while configuring this activity. Defaults to index.html.
  • configModal.height - Property that defines the height of the iframe containing the configuration UI.
  • configModal.width - Property that defines the width of the iframe containing the configuration UI.
  • configModal.fullscreen - If true, forces the configuration UI to take up the entire screen. Defaults to false. This parameter overrides any defined height and width.
schema Object No Object mirrors the activity configuration from the top level of the config.json file and specifies schema information about in and out arguments. Schema objects follow this pattern:
{
"dataType": MC data type,
"isNullable": Boolean,
"direction": "in" or "out",
"access": "visible" or "hidden"
}
The context of the call implies the direction of the arguments in the schema, making this value optional. Any provided value must match the context. You cannot include a null value for any declared outArguments, as the call requires these values. Therefore, assume isNullable to be false. For all access property parameters not set to visible, subsequent expression builders do not show this out argument.