Screen Shot 2015-07-20 at 7.15.09 AM.png

Custom Activities in Marketo

John_M
Marketo Employee
Marketo Employee

Summary

One of the more recently introduced features in Marketo is Custom Activities. We all know about the built in Activities Marketo provides out of the box, and you can see that list using the Get Activity Types REST API Endpoint, but what's a "custom" activity?

Well essentially it's analogous to a built in activity in structure and purpose in every way, only you define it as an action a user has taken that is relevant to your business, and you add those activities through a special REST API Endpoint. Just like Marketo activities, you get a Filter and Trigger associated with the new custom activity that you can use in your smart lists

Custom activities are currently a beta feature in Marketo, but are currently in production with a fair few clients. They must actually be created in your instance by consulting or support, so once you define their attributes, you can work with professional services or support to get the activities themselves created. Once that's done, you can use the API to populate them.

Defining A Custom Activity

The following aspects of a custom activity must be defined to create it in Marketo.

- Name : The name of the custom activity (that one's a bit obvious)

- Description (Optional) :

- Trigger Name : This is the name Marketo will give to the Trigger associated with this custom activity

- Filter Name : This is the name Marketo will give to the Filter associated with this custom activity

- Attributes : This is the list of all the relevant attributes on the activity. The possible datatypes are the usual suspects.. integer, float, string, boolean, and datetime

Screen Shot 2015-07-20 at 7.15.09 AM.png

Example

The example I've chosen is "Purchase Product". When a Lead purchases a product, you might want to send a welcome email, or add that lead to  nurture stream. When passing on your request, you should have these ready to give to support or consulting in a concise format to avoid confusion. Note that you do NOT need a "purchaseDate" attribute, as Marketo give you a "date of activity" attribute for free.

- Name : Purchase Product

- Description (Optional) : a lead purchases a product!

- Trigger Name : Purchases Product

- Filter Name : Has Purchased Product

- Attributes :

     productID: string

     productName: string

     productDescription: string

Once the object is created, support will supply an Activity ID to you, which you'll use in your REST API calls to add activities. Be sure to make a note of it! In my case, that ID is 100006.

Let's take a look! The following screenshot shows the Trigger and two Filters that are created for you, and notice that your custom activity attributes are available as constraints. Cool right?!?! Think of all the cool possibilities. One thing that comes to mind is the creation of an activity like "Custom Form Fill". If you're using the SOAP or REST API to handle form fills in a custom way rather than using Marketo Forms, you don't get a "form fill" event.. but now you can emulate that with a custom Activity!

Screen Shot 2015-07-20 at 7.31.07 AM.png

Adding Activities

Now that you have your shiny new activity, lets add some using the REST API. For this example, I use Postman, and I really recommend it. It simplifies the process of interacting with the REST API. Note if you arent comfortable creating timestamps, there is help available! Check out sites like the Timestamp Generator / Converter - Timestampgenerator.com

Screen Shot 2015-07-20 at 8.38.14 AM.png

Request (note that you can send in many activities in one request)

{

   "input":[

      {        

         "leadId":34,

         "activityDate":"2015-07-20T12:30:00-08:00",

         "activityTypeId":100006,

         "primaryAttributeValue":"SKU12345",

         "attributes":[ 

            {

                "name": "productName",

                "value": "iPhone"

            },

            {

                "name": "productDescription",

                "value": "iPhone 6s+"

            }

         ]

      },

      {        

         "leadId":34,

         "activityDate":"2015-07-20T12:30:00-08:00",

         "activityTypeId":100006,

         "primaryAttributeValue":"SKU12346",

         "attributes":[ 

            {

                "name": "productName",

                "value": "Apple Watch"

            },

            {

                "name": "productDescription",

                "value": "Apple Watch Edition"

            }

         ]

      }

  ]

}

Response:

{

  "requestId": "94a2#14eac235e1a",

  "result": [

    {

      "id": 76356,

      "status": "added"

    },

    {

      "id": 76357,

      "status": "added"

    }

  ],

  "success": true

}

Viewing Activities

Just like normal activities you can view these in campaign result, and also in lead details under the activity tab.

Screen Shot 2015-07-20 at 8.47.13 AM.png

Limitations and Considerations

- The volume limit for these activities is a bit fluid, but we recommend keeping under 100,000 per day. That limit can be revisited depending on usage.

- Custom Activities cannot be used in email scripting. Think of them like normal activities.

6086
16
16 Comments
Chelsea_Kiko
Level 6 - Champion Alumni

Hey Emma Wu

Net new leads are not added into MKTO via API if you set up custom activities. We actually found a solution that works - so if you want more info or need help, let me know!

Supporto_BOARD
Level 2

I'm currently looking into this for the possibility of tracking on-site searches. Has anyone ever used Custom Activities in such a scenario?

Thanks,
Francesco

SanfordWhiteman
Level 10 - Community Moderator

That's a really bad -- and unnecessary -- idea. Marketo already logs searches as regular web activities, and if you use the query param

 

  s=search+terms

you even get a trigger token {{trigger.search query}}.

Supporto_BOARD
Level 2

Hi Sanford,

the URL you end up on when doing a search is built like this: www.company.com/language/search/node/search%20terms

So, I know I can create some logic based on "Visited web page - contains /search/node/..." to get the list of people who searched for specific terms. The issue here is that I have no way of distinguishing this as a separate activity at a high level, nor I can have the information evident unless I specifically ask for it. I'm working with a customer that is switching from Pardot, and one of the things they could do was to specifically track searches made on the site; I don't know how that works in Pardot as I wasn't on that project, but from what I could gather the end result was that search activities were separated from simple page views, and the Sales Insight equivalent for Pardot showed each search performed by a Person.

I think I can build a Smart Campaign to handle this, but having never done it I'm not sure if and how that would work. Would this be the correct structure?

Search Smart Campaign.png

I get that maybe this wouldn't work because we're not using the "s=search+terms" parameter, but I'm trying to understand the correct approach first and then see if we can change the search behaviour to adapt it to Marketo.

Are there other possibilities in case we can't change how search behaves today?

Thanks,

Francesco

SanfordWhiteman
Level 10 - Community Moderator

Supporto BOARD​ as Blog comments don't have a full JS syntax highlighter, I'm opening a new thread in Products​ to continue.

Rob_Alfieri
Level 2

Special note in case folks don't realize it. When adding your attribute fields, if you use "name", you must use the Display Name for the attribute. If you want to use the API name, use "apiName". Drove me crazy.  Example below.

{

"input": [

{

  "leadId": 2000950,

  "activityDate": "2018-04-01T23:18:34Z",

  "activityTypeId": 100008,

  "primaryAttributeValue": "PEPTIDE XB-C18",

  "attributes": [

  {

  "apiName": "productBrand",

  "value": "Aeris"

  },

      {

      "apiName": "orderNumber",

      "value": "APR012018"

      },

  {

  "apiName": "productSKU",

  "value": "PEPXBC18"

  },

  {

  "apiName": "orderDate",

  "value": "2018-04-01"

  },

  {

  "apiName": "orderQuantity",

  "value": 1

  },

  {

  "apiName": "productPromo",

  "value": "None"

  }

  ]

}

]

}