updated on Blog

Journey Builder Custom Activity Deep Dive

Introduction

In the previous article, we have reviewed various types of custom components that exist in Marketing Cloud. Today we will describe in detail the development of the first and most popular component – Journey Builder Activity.

At the end of the previous article, we talked about the steps that must be followed before we start developing. At this point, we will assume that you have successfully created an installed package and registered an account on Heroku.

Next, we’ll go through the source code of our custom Journey Builder Activity, go through the steps required to deploy and configure the application on Heroku, then connect our application to Marketing Cloud and test it using Journey Builder and logs.

Use Case

For this article, I decided to pick a primitive use case since the main focus will be rather on describing the steps needed to build, deploy and configure the custom application in Salesforce Marketing Cloud.

So, let’s assume that we need a custom activity that can be used to log journey entry/exit events for each contact along with some comment into the Data Extension.

Source Code

We have prepared the repository which you can fork to start working on your own custom activities: https://github.com/sfm-cz/journeybuilder-custom-activity

Now, let’s figure out the structure of this component. The component is a NodeJS application using the Express.js framework. Pug, formerly known as Jade, is used as a template engine.

App.js is the entry file of the application where all the necessary routes and libraries are connected and the application itself is configured. We tried to comment on the code at greater length in order to make it clearer and easier for you to start.

All the necessary routes are stored in the routes folder:

  • Index.js contains the UI of the custom activity
  • Activity.js contains the minimum required endpoints for a custom activity, namely:
    • Execute is invoked when a person enters a custom activity
    • Save is invoked when Journey is activated
    • Publish is invoked when Journey is validated successfully
    • Validate is invoked before Save and by clicking Validate in the  interface of Journey Builder

The utils folder contains useful utilities for working with Marketing Cloud, logging data (we use winston) and a utility for verifying data that came from Marketing Cloud using JWT.

The Views folder contains a template for rendering Custom Activity UI. We prefer to use the template engine instead of plain HTML because it allows us to get dynamic data and transfer it to the template. For instance, we can load some data from the Data Extension and use it as a value for the Dropdown list.

The Assets folder contains static files: pictures, styles, JavaScript.

I recommend paying attention to customActivity.js, which implements the ability to save and read settings from Marketing Cloud using Postmonger.

Also at the root of the project, you will see an .eslintrc file that helps us write code within a command in the identical style and using Eslint.

Heroku – Deployment and Configuration

When your code is ready for deployment, you can proceed with the steps below:

  1. Go to your applications page on Heroku and in the upper right corner click New – Create new app.
  1. Give your app a name, select a region and click Create app.
  1. Once you appear in the Deployment tab of your application, in the Deployment method section, select GitHub.
  1. In the newly appeared Connect to GitHub section, select your GitHub account, and then enter the names of your repository and click Search. Then click Connect.
  1. Now that your application is ready for code deployment from your GitHub account, you can (optionally) enable automatic deployments. To do this, go to the Automatic deploys section, select your repository branch and click Enable Automatic Deploys.
  1. You can also do manual deployment when needed. To do this, select the repository branch in the Manual deploy section and click Deploy Branch.
  1. Deploy your code and make sure that build succeeded. For that, navigate to the Overview tab and check the list of latest activities.
  1. Now we need to configure the Variables that are used in our application. Heroku’s Config Vars is a way to avoid storing sensitive information such as IDs and keys inside your application code. Instead, they are securely stored on Heroku and get populated during the code execution using the following syntax: process.env.VARIABLE_NAME. To configure the Config Vars, navigate to Settings tab and in the Config Vars section click Reveal Config Vars. Now you need to add the following variables:

Note: If you want to run your application locally before deploying it to Heroku you can store all your config vars in .env file. Don’t forget to add .env to your .gitignore file to avoid pushing it to Git.

That’s all for now. Although we haven’t finished configuring the variables yet, now we need to set up the connection in Marketing Cloud. Don’t worry, we’ll come back to Heroku in a moment. Therefore, leave the current browser window open.

Marketing Cloud – Installed Package and DE Configuration

  1. Log into the Marketing Cloud and navigate to Setup -> Apps -> Installed Packages, choose the Installed Package you have previously created and click Add Component.
  1. Then choose API Integration and click Next.
  1. Choose Server-to-Server and click Next.
  1. Give the Data Extensions (Read, Write) permissions. Click Save.
  1. Your installed package is ready but we are not done with it yet. Leave this browser tab open for now and navigate to Data Extension creation in Email Studio or Contact Builder. Create the new Data Extension with the following fields:

Note that the Date field will be populated by Marketing Cloud Itself.

  1. Now you have everything to complete your Config vars in Heroku. Go back to your app’s Settings in Heroku and fill in the values:

Note: Due to the security enhancements in one of the latest commits you would also need to add the ‘STACK’ variable and assign it a value of your Marketing Cloud Stack (e.g. s10, s50, etc.).

  1. Let’s make sure that everything works. To do this, click Open app. You should see the UI of your application.
  1. All that’s left is to complete the setup in Marketing Cloud and we’ll be ready to test. Go back to your Installed Package window and click Add Component. Choose Journey Builder Activity and click Next.
  1. Name your custom activity, choose the category where you want it to be displayed, paste your Application URL, and click Save

Hooray! We are done with the configuration and our app is ready for testing. Let’s jump into the Journey Builder and proceed with our custom activity configuration and testing.

Journey Builder – Custom Activity Configuration and Testing

We are already at the finish line and will soon be able to see the result of our effort. First, create a new Journey in the Journey Builder and configure it. Configure the Entry Source as you wish, set your preferred Contact entry policy and drag your custom activity into the Journey canvas. You will find your custom activity in the category you selected when creating the component. You can always go back to the component settings and choose a different category.

Now open your custom activity and fill it in as shown in the picture:

Add another custom activity and fill it like this:

In both examples above, remember to replace DENAME with the name of your Data Extension, and ATTRIBUTENAME with the name of the attribute you want to use. If you are not familiar with this syntax, we recommend reading about Data Binding. Most importantly, make sure the Data Extension you choose is in the Attribute Group inside the Data Designer. You can also use the attributes of your Entry Source using the syntax: {{Event.EventDefinitionKey.AttributeName}}. Don’t forget to replace the EventDefinitionKey and AttributeName with actual values.

So, after you’re done, your Journey canvas should look similar to this one:

If something went wrong, we recommend looking at the logs on Heroku first. There are two options:

Using the Web Interface, open your application and click More -> View logs:

This method is not the most convenient because you will only see the last few lines from the logs. It’s way cooler to use the Command Line Interface!

Of course, at first you need to install it: https://devcenter.heroku.com/articles/heroku-cli#download-and-install

Then you should log in using the heroku login command

Next you can view the logs using the command:

Heroku logs --tail --app application_name

We also recommend installing one of the free addons for storing logs, this can be useful for debugging: https://elements.heroku.com/addons#logging

You can check the result of data recording in your Data Extension.

Conclusion

So, let’s sum up. In this article, we have gone through:

  • How to develop custom Journey Builder Activities
  • How to deploy and configure them on Heroku
  • How to connect them to Marketing Cloud
  • How to test them and check the logs

Stay tuned for more custom components in the following articles:

  • Journey Builder Decision Split
  • Journey Builder Entry Source
  • Content Block
  • Marketing Cloud Application
Spread the love
Avatar photo

Orkhan Alakbarli

Salesforce Technology Director