Walkthrough: Add an activity type to the Marketing Automation UI

Current version: 9.2

Activity types define what action the Marketing Automation Engine takes when it enrolls a contact a campaign. There are several built-in activity types, but you can also create custom activity types.

When you have created an activity type, you must add it to the Marketing Automation (MA) user interface for the content authors to be able to use it. You do this with the help of a TypeScript class contained in a Node Package Manager (NPM) package combined with an Angular based activity editor to form a MA plugin.

This walkthrough tells you how to do the following tasks:

Important

You must create a project folder on your workstation for the TypeScript, JSON, JavaScript, and XML files. This folder does not have to be the same folder where you created your activity type. In this walkthrough, your project folder is referred to as the <project folder>.

Create the NPM package

The basis of an NPM package is the package.json file. You can add other NPM packages to the package to easily extend its functionality.

To create the NPM package:

  1. In the <project folder>/ folder, create a sample/ folder.

  2. Go to the sample/ folder and use NPM to create the package.json file:

    RequestResponse
    npm init
    Note

    NPM names the package after the package folder name, and you do no need to select custom values for any of the optional fields (version, description, entry point, test command, git repository, keywords, author, and license).

  3. In the package.json file, add the missing dependencies:

    RequestResponse
    sample/package.json (for Sitecore 9.1+)

"dependencies": {
  "@sitecore/ma-core": "<wwwroot>/<sitecore instance>/sitecore/shell/client/Applications/MarketingAutomation/packages/ma-core",
  "@angular/common": "5.2.11",
  "@angular/compiler": "5.2.11",
  "@angular/compiler-cli": "5.2.11",
  "@angular/core": "5.2.11",
  "@angular/forms": "5.2.11",
  "@angular/http": "5.2.11",
  "@angular/platform-browser": "5.2.11",
  "@ngx-translate/core": "9.0.2",
  "rxjs": "5.5.11",
  "zone.js": "^0.8.4"
},
"devDependencies": {
  "ts-loader": "4.4.2",
  "typescript": "2.5.3",
  "webpack": "4.43.0",
  "webpack-cli": "3.3.11"
}

  4. Save the package.json file.

  5. Install the missing dependencies with the following command:

    RequestResponse
    npm install

Create the activity type

The activity type is where you define your custom business logic. The @sitecore/ma-core package contains the following built-in activity types that you can extend:

To create the activity type:

  1. Go to the <project folder>/sample/ folder.

  2. Create a src/ folder.

  3. Go to the src/ folder and create a sample-single-item-activity-type.ts file.

  4. Copy the sample TypeScript implementation from the SingleItem activity type.

  5. Add your optional custom code.

  6. Save the sample-single-item-activity-type.ts file.

Create the activity editor

You must create a activity editor (a graphical user interface) for the content authors to use when they are defining campaign activities based on the activity type.

To create an activity editor:

  1. Go to the <project folder>/sample/src/ folder.

  2. Create an editor/ folder.

  3. In the editor/ folder, create a sample-single-item-editor.component.ts file.

  4. Copy the sample TypeScript component implementation from the activity editor.

  5. Add your optional custom code.

  6. Save the sample-single-item-editor.component.ts file.

  7. Create a sample-single-item-editor.module.ts file.

  8. Copy the sample TypeScript module implementation from the activity editor.

  9. Save the sample-single-item-editor.module.ts file.

Prepare the MA plugin

The MA plugin is where the activity type and activity editor are combined.

To prepare the MA plugin:

  1. Go to the <project folder>/sample/src/ folder.

  2. Create a sample.plugin.ts file containing the following TypeScript code:

    RequestResponse
    sample/src/sample.plugin.ts

import { Plugin } from '@sitecore/ma-core';

@Plugin({
  activityDefinitions: [ ]
})

export default class SamplePlugin {}
    Important

    Do not add the activity type to the activityDefinitions section at this point.

    Note

    The export default statement makes the plugin the default export of the package. This is necessary for the MA application to discover it.

  3. Save the sample.plugin.ts file.

Configure the Angular AOT compiler

To compile TypeScript code, you must configure the Angular ahead-of-time (AOT) compiler .

To configure the Angular AOT compiler:

  1. Go to the <project folder>/sample/ folder.

  2. In the package.json file, add the Angular AOT compiler dev script:

    RequestResponse
    sample/package.json

"scripts": {
  "test": "echo \"Error: no test specified\" && exit 1",
  "dev": "ngc -p ./src/tsconfig.aot.json"
}
    Note

    The Angular AOT compiler generates a factory for each MA plugin. This factory is required to register the activity editor modules with the plugin decorator.

  3. Save the package.json file.

  4. Create a tsconfig.json file containing the following JSON structure:

    RequestResponse
    sample/tsconfig.json

{
  "compilerOptions": {
    "emitDecoratorMetadata": true,
    "experimentalDecorators": true,
    "target": "es5",
    "module": "es2015",
    "moduleResolution": "node",
    "removeComments": true,
    "sourceMap": true,
    "outDir": "./codegen",
    "rootDir": "./",
    "declaration": true,
    "lib": [
      "es2016",
      "dom"
    ],
    "baseUrl": ""
  }
}

  5. Save the tsconfig.json file.

  6. In the src/ folder, create a tsconfig.aot.json file containing the following JSON structure:

    RequestResponse
    sample/src/tsconfig.aot.json

{
  "compilerOptions": {
    "emitDecoratorMetadata": true,
    "experimentalDecorators": true,
    "target": "es5",
    "module": "commonjs",
    "moduleResolution": "node",
    "removeComments": true,
    "sourceMap": true,
    "outDir": "../codegen",
    "rootDir": "./",
    "declaration": true,
    "lib": [
      "es2016",
      "dom"
    ]
  },
  "angularCompilerOptions": {
    "genDir": "../codegen",
    "skipMetadataEmit": true,
    "generateCodeForLibraries": true
  }
}

  7. Save the tsconfig.aot.json file.

Compile the activity type and the activity editor

You must compile the TypeScript of the activity type and the activity editor and add them to the MA plugin.

To compile and add the activity type and editor to the MA plugin:

  1. Go to the <project folder>/sample/ folder.

  2. Use the Angular AOT compiler to create the codegen/ folder and compile the TypeScript with this command:

    RequestResponse
    npm run dev

Add the activity type and the activity editor to the MA plugin

You must add the activity type and the activity editor to the activityDefinitions property of the MA plugin.

The activityDefinitions property is an array of ActivityDefinition objects. Each object has the following required properties:

Property

Type

Description

id

string

The Sitecore activity item ID that exists in the Master database under the sitecore/System/Settings/Analytics/Marketing Automation/Activity Types item.

activity

ItemBase

The activity class that must extend the SingleItem, FinalItem, ConditionItem, or DecisionPointItem class.

editorComponent

EditorBase

The activity editor class that must be referenced from the codegen/ folder.

editorModuleFactory

NgModuleFactory<any>

A factory artifact that is generated by the Angular AOT compiler.

To add the activity type and activity editor to the MA plugin:

  1. In the <project folder>/sample/src/ folder, in the sample.plugin.ts file, add the following import statements and activityDefinitions:

    RequestResponse
    sample/src/sample.plugin.ts

import { Plugin } from '@sitecore/ma-core';
import { SampleSingleItemActivityType } from './sample-single-item-activity-type';
import { SampleSingleItemModuleNgFactory } from '../codegen/editor/sample-single-item-editor.module.ngfactory';
import { SampleSingleItemEditorComponent } from '../codegen/editor/sample-single-item-editor.component';

@Plugin({
  activityDefinitions: [
    {
      // The ID of the sitecore activity item that exists in the Master database under
      // sitecore/System/Settings/Analytics/Marketing Automation/Activity Types item
      id: '5908ca79-1089-440b-9af1-a2f47766a783',
      activity: SampleSingleItemActivityType,
      editorComponenet: SampleSingleItemEditorComponent,
      editorModuleFactory: SampleSingleItemModuleNgFactory
    }
  ]
})

export default class SamplePlugin {}

  2. Save the sample.plugin.ts file.

Configure the webpack module bundler

You must configure the the webpack module bundler to combine the plugin artifacts together into a single output file.

Important

The MA application uses SystemJS to load plugins. This means that the plugin module format can be any of the formats supported by SystemJS. Here we use the Universal Module Format (UMD) as defined in the libraryTarget property.

To configure the webpack module bundler:

  1. Go to the <project folder>/sample/ folder.

  2. Create a webpack.config.js file with the following JavaScript code:

    RequestResponse
    sample/webpack.config.js

var path = require("path");

module.exports = {
  entry: "./src/sample.plugin.ts",
  module: {
    rules: [
      {
        test: /\.ts$/,
        use: "ts-loader",
        exclude: path.resolve(__dirname, "node_modules")
        }
      ]
  },
  resolve: {
    extensions: [".ts", ".js"]
  },
  output: {
    path: path.resolve(__dirname, "dist"),
    filename: "sample.plugin.js",
    library: "samplePlugin",
    libraryTarget: "umd"
  },
  externals: [
    "@sitecore/ma-core",
    "@angular/core",
    "@ngx-translate/core"
  ]
};
    Note

    The MA application provides the @sitecore/ma-core, @angular/core, and @ngx-translate/core libraries at runtime. If they are not configured as externals, they are bundled with the plugin artifacts, and the plugin cannot load.

  3. Save the webpack.config.js file.

  4. In the package.json file, add the webpack build script:

    RequestResponse
    sample/package.json

"scripts": {
  "test": "echo \"Error: no test specified\" && exit 1",
  "dev": "ngc -p ./src/tsconfig.aot.json",
  "build": "webpack"
}

  5. Save the package.json file.

Build the MA plugin.

You must build the single-file MA plugin to deploy it to the MA application.

To build the MA plugin:

  • In the <project folder>/sample/ folder., build the MA plugin to the dist/sample.plugin.js file with this command:

    RequestResponse
    npm run build

Deploy the MA plugin

You must deploy the MA plugin to Sitecore so that the MA application can discover it.

To deploy the plugin:

  1. Go to the <project folder>/sample/ folder.

  2. Deploy the MA plugin file to the MA application with this command:

    RequestResponse
    cp dist/sample.plugin.js <webroot>/sitecore/shell/client/Applications/MarketingAutomation/plugins/

  3. Create a SamplePlugin.config configuration file with the following XML:

    RequestResponse
    SamplePlugin.config

<?xml version="1.0" encoding="utf-8"?>
<configuration>
  <sitecore>
    <marketingAutomation>
      <pluginDescriptorsRepository>
        <plugins>
          <!-- Assuming that the plugin bundle file name is sample.plugin.js
          and is deployed directly under the plugins folder -->
          <plugin path="./plugins/sample.plugin.js" />
        </plugins>
      </pluginDescriptorsRepository>
    </marketingAutomation>
  </sitecore>
</configuration>

  4. Deploy the SamplePlugin.config configuration file to the MA application with the following command:

    RequestResponse
    cp SamplePlugin.config <webroot>/App_Config/Include/

Check the activity type

You must check if the activity type is available to the content authors in the MA user interface.

To the check the activity type:

  1. In the Sitecore Launchpad, click Marketing Automation.

  2. Open an existing campaign or create a new one.

  3. In the Toolbox pane on the right hand side of the screen, check if the activity type is present.

Do you have some feedback for us?

If you have suggestions for improving this article,