Custom Activities Quick Start

Tyron_Pretorius
Level 9 - Champion Level 9 - Champion
Level 9 - Champion

As a Marketo user I am sure you are aware of the standard activities that Marketo tracks such as email opens, webpage visits, and form fills. But what about the wealth of activities that are unique to your business? How can you get these into Marketo? Custom activities that’s how!

 

Custom activities are a powerful way to get your business’s unique customer behavior into Marketo so that you can get deeper insights into your customer’s behavior and use these custom behaviors as smart list filters and triggers to enhance your automation and personalized outreach.

 

The documentation on custom activities is sparse, to say the least, but don’t you worry in this blog post I will explain what a custom activity is, how we can set one up, how we can test it works, and how we can send custom activities from our code.

 

 

What is a Custom Activity?

 

A custom activity is an activity that you define upon creation with a primary field and supplementary fields which then become the constraints of this activity in smart list filters and triggers. Custom activities also appear in the activity log so that you can see these activities alongside all the standard activities which are tracked in Marketo.

 

If you use the Segment CDP and you want to map your Segment events to custom activities then check out the “Mapping a Custom Activity to a Segment Event” section in this blog post.

 

Custom Activity Primary Field

 

The custom activity primary field, designated by the asterisk in the image below, is a field that must always be present when the activity is being sent to Marketo and it must be of the string data type. As explained by Justin Norris, the primary field for a Marketo activity usually refers to the object that the activity refers to:

  • For “Visits Web Page” the primary field would be “web page”
  • For “Fills out Form” the primary field would be “form”
  • For “Opens Email” the primary field would be “email”

 

Tyron_Pretorius_0-1716942430435.png

 

Custom Activity Fields

Tyron_Pretorius_1-1716942430580.png

 

Custom Activity Trigger and Filter Showing Available Constraints

 

So for example in the images above a more applicable primary field could have been “number” for the “Number Search” custom activity, provided that this activity always has a “number” property present when it is being sent to Marketo.

 

As you see in the images though, the “timestamp” field is used as the primary field and you can see how it is displayed as the primary constraint on the trigger and filter for the custom activity. When you are merely trying to trigger or filter for the custom activity the value of this primary constraint does not matter, hence why the “is not empty” condition is used in the images above.

 

Consequently, the choice of primary field does not matter so long as it is always present when the activity is being sent to Marketo and it is of the string data type.

 

Other Custom Activity Fields

 

You only need to have the primary field set for the custom activity to function correctly. However, if you want to have additional constraints available on the custom activity filters and triggers then you will need to create more fields on the custom activity (see images above).

 

If you want to find out how you can transfer values from these custom activity fields into person fields then check out the Trigger Tokens with Custom Activities section.

 

Creating a Custom Activity

 

Tyron_Pretorius_2-1716942430460.png

 

Custom Activity Details

  1. Navigate to “Admin” > “Custom Activities”
  2. Click on “New Custom Activity”
  3. Fill out the “Display Name” and modify the “API Name” if you wish
  4. Click “Next”
  5. Fill out the “Filter” and “Trigger” names
  6. Click “Next”
  7. Fill out the “Name” and “API Name” of the primary field
  8. Click “Submit”

 

For any additional activity fields that you want to use as constraints on the filter and trigger:

 

  1. Navigate to the “Fields” tab
  2. Click “New Field”
  3. Select the field “Data Type”
  4. Enter a “Name”
  5. Rename the “API Name” field if you wish
  6. Hit “Save”

 

Finally, to approve the custom activity and get the “Custom Activity ID”:

 

  1. Click the “Custom Activity Actions” dropdown
  2. Select “Approve Activity”
  3. Copy the Custom Activity ID that appears once the activity is approved

 

You will need this custom activity ID when mapping the activity to an event from another platform like Segment and when making API requests to send this activity to Marketo using Postman and code (see the section below).

 

Sending a Custom Activity to Marketo

 

Once you have created the custom activity and copied the activity ID you are then ready to test that it works. To do this we are going to use the free API testing tool called Postman. If it is your first time using Postman and the Marketo API I highly recommend checking out the API Quick Start Guide, which will show you how to make your first API requests in Postman.

 

In the quick start guide, there is also a form that will allow you to download the Marketo API Postman collection which includes the request we are going to use below to send a custom activity to Marketo.

 

Sending a Custom Activity Using Postman

 

Tyron_Pretorius_3-1716942430804.png

 

Postman request to send custom activity to Marketo

 

To build this API request we are going to make a POST request to the endpoint below.

 

{{base_url}}/rest/v1/activities/external.json

 

Then we will specify the custom activity ID, the primary field value, and the values for any other fields present in our custom activity. We also have to specify the timestamp for when the activity occurred (this will be the time it is displayed in the activity log) along with the lead ID for the person who carried out this activity.

 

{
	"input": [{
		"activityDate": "{{Timestamp}}",
		"activityTypeId": {{Activity ID}},
		"attributes": [
                      {
			"apiName": "{{Field 1 API Name}}",
			"value": {{Field 1 Value}}
		       } ,
                       {
			"apiName": "{{Field 2 API Name}}",
			"value": {{Field 2 Value}}
		       },
                      {
			"apiName": "{{Field 3 API Name}}",
			"value": {{Field 3 Value}}
		       }
                 ],
		"leadId": {{Lead ID}},
		"primaryAttributeValue": "{{Primary Field Value}}"
	}]
}

 

Once we send this custom activity to Marketo we can then check the activity log for the lead whose lead ID we specified in the API request. Make sure to check the activity log around the same time as the activityDate we specified in the API request above.

 

N.B. The API works on UTC time so when you specify the activityDate value that the time will appear differently in the activity log of your Marketo instance (presuming your instance is not on UTC time).

 

Sending Custom Activities from Your Code

 

Tyron_Pretorius_4-1716942430480.png

 

Getting the code for sending a custom activity to Marketo

Once you have configured the request in Postman to send the custom activity to Marketo, Postman makes it super simple to export this request in any programming language of your choosing.

 

  1. Click on the code icon on the right-hand-side
  2. Select your preferred programming language from the dropdown
  3. Copy and paste the generated snippet into your code

 

It’s that easy!

Don’t you just love Postman 

 

What’s After Custom Activities?

 

Now that you know how to set up custom activities in Marketo and have gotten exposure to the API why don’t you check out the posts below to further your knowledge of the API and what it can do for you:

4053
8
8 Comments
ktronolone
Level 3

Thanks so much for sharing this @Tyron_Pretorius - it really makes the process seem very easy. 

To help my understanding, do you see this as a tool for activities that happen outside of Marketo and can make the API transaction to post the data? Possibilities for activities within Marketo? 

Currently I use Interesting Moments for activities that I want to be able to call up easily so that it doesn't require complicated filters about which form on which page, etc. So I'm curious if a custom activity might be a simpler solution, and something that folks who don't have Interesting Moments can adopt. 

Tyron_Pretorius
Level 9 - Champion

Custom activities are great for getting activities unique to your business into Marketo. For example, at my company, we have an online portal where people can buy sim cards, create a messaging profile, add a credit card etc and we use custom activities as a way to get these events into Marketo so we can use them in our MQL mechanism

 

I do not have access to interesting moments but I do not think they can be used to get the sort of events I mention above into Marketo

Zoe_Forman
Level 9 - Community Advisor + Adobe Champion

Great post @Tyron_Pretorius 

Our use case of Custom Activities is for tracking Social Media engagements, across multiple platforms and posts.

@ktronolone Similar we do not have Interesting Moments. Smart lists and Subscriptions meet our needs.

michellechopin
Level 7 - Community Advisor

This is a great post, @Tyron_Pretorius! I just set up Custom Activities for an integration and I wish I had read this post before that as it clarified a few things for me that I stumbled through on my own 😋

 

How does one get around the limit of 10 Custom Activities in Marketo? We are using 7 for this particular integration (like @Zoe_Forman, ours is for tracking Social Media engagements), so we'd likely run into an issue if a future tool required more than 3 Custom Activities.  

SanfordWhiteman
Level 10 - Community Moderator

It’s pretty unusual (a sign of poor design) to need 7 CA definitions for a single tool. What are those definitions and why can’t they be consolidated into one CA with different additional properties?

michellechopin
Level 7 - Community Advisor

@SanfordWhiteman Those are the CA's that were created with the integration as soon as Marketo was connected - they're not created manually (as I learned after the fact 😋). I'm assuming that there are multiples because each tracks something different and pulls unique IDs - there are only two CAs that look like they're similar/related (likes vs engagements) and I believe it's based on the applicable network and API.

SanfordWhiteman
Level 10 - Community Moderator

Pretty presumptuous of them! That’s not something a professional integration should do — what if you didn’t have 7 to give? At any rate it’s unlikely they need 7, as you can set the context via other fields.

Tyron_Pretorius
Level 9 - Champion

@michellechopin I think you might be able to ask you CSM for more custom activities if needed

 

My company were one of the early testers of custom activities so I do not think we have a limit, we currently have over 20 CAs in our instance