Marketo

Marketo is an account-based marketing software suite with an array of tools, and is commonly used in conjunction with other CRM products. Using the Marketo data source type, it is possible to access various Marketo objects.

Due to the way the Marketo API functions, this data source type is best used for cross-referencing Marketo information with other data sources, as opposed creating a new UI for Marketo within Skuid. This is particularly useful within CRM dashboards, allowing end users to see the activities a person—also known as a lead—has participated in, or add that person to lists. Most accessible objects are read-only and are intended only for reference.

Configuration

As with other data sources, accessing a Marketo instance through Skuid requires a Client ID and Client Secret to properly create an authentication provider and then using that authentication provider for a Marketo data source.

Note

  • In the below instructions, you will need to use the appropriate URL for your Marketo instance’s REST API. Insert your instance’s information wherever you see your-marketo-url.

    If you do not know this URL, you can find it in the Marketo Admin menu, under Integration > Web Services in the REST API pane.

  • You will need an API Only user within Marketo to obtain the proper API credentials. Be sure to follow the Getting Started section of Marketo’s REST API documentation to configure this properly.

In Marketo

Retrieve client ID and client secret API credentials for your Marketo instance. To do so, follow the steps listed in the Getting Started section of Marketo’s REST API documentation.

In Skuid

First, create an authentication provider to access your Marketo instance using the API credentials from above.

  1. Navigate to Configure > Data Sources > Authentication Providers.
  2. Click New Authentication Provider.
  3. Update the following fields:
    • Name: Enter a unique name, such as MarketoAuth.
    • Authentication Method: OAuth 2.0 / OpenID
    • Provider Type: Other
    • Grant Type: Client Credentials
    • Token Endpoint: https://your-marketo-url.mktorest.com/identity/oauth/token
    • Client ID and Client Secret: Enter the API credentials for your Marketo instance.
  4. Click Save.
  5. If Skuid asks you to create a Remote Site Setting, click OK.

With the authentication provider now configured, create a data source that points to your Marketo instance.

  1. Navigate to Configure > Data Sources > Data Sources.

  2. Click New Data Source.

  3. Select the Marketo data source type.

  4. Enter a unique name for your data source, such as Marketo.

  5. Click Next Step.

  6. Update the following fields:

    • URL / Endpoint: https://your-marketo-url.mktorest.com/

      Warning

      Be sure that there is a slash / at the end of your endpoint URL.

    • Authentication Method: Authentication Provider

  7. Select the authentication provider you created in the previous section.

  8. Click Save new Data Source.

  9. If Skuid asks to create a Remote Site Setting, click OK.

Usage

The Marketo data source type is primarily used to access the persons—or “leads”—stored within a Marketo instance, though custom objects are also available. Connect a Skuid model to one of these objects, and use that model with any Skuid component that suit your use case, such as the Table, Deck, or Field Editor components.

Some of the most commonly used objects include Person, StaticList, and Program.

Person

Also known as Lead, this object contains all standard and custom info for Marketo persons. Person records are creatable and editable, but all models connected to the Person object must have a condition set. The type of conditions available are determined by the Fetch Persons By property.

Because the Person object always requires a condition, pairing this object with another—such as StaticList or Program—is recommended.

Fields and Conditions

  • Fields:
    • All standard Person fields—First Name, Billing Address, etc.—are available.
    • All custom fields, noted by having __c appended to the end of their name.
  • Conditions: Available conditions are determined by the Fetch Persons By model property and a condition must be set.
    • Static List: Query all Person records on a specific Marketo list. Lists can be obtained in the StaticList object.
    • Program: Query all Person records connected to a specific Marketo program.
    • ID: Query one Person record based on its specific ID. Useful for detail pages.

Campaign —``

The Campaign object relates to Smart Campaigns in Marketo, which are typically contained within programs. This read-only object can be used to survey and reference preexisting campaigns.

Fields and Conditions

  • Fields: Standard fields are available.
  • Conditions: Campaigns may be limited by their campaignID—meaning data from only one campaign will be displayed. Useful for campaign detail pages.

Program

Programs are Marketo marketing initiatives and serve as containers for a variety of Marketo assets. You can both create and edit Program records, but the following fields must be present:

  • Channel
  • Folder Id—specifying a folder name will not suffice. Having a Folder model is recommended because of this.
  • Folder Type (which must match the folder specified in the Folder ID field)
  • Name
  • Type

Fields and Conditions

  • Fields: Standard and custom fields are available.
  • Conditions: Programs may be filtered by tag type and tag value, but if one condition is set and activated, the other must be as well.
    • tagType
    • tagValue

Folder

This object queries for all available Marketo folders—which are used to organize campaigns and assets. Subfolders will also be viewable, through the depth of subfolders displayed is based on the folder depth condition.

Fields and Conditions

  • Fields: Standard and custom fields are available.
  • Conditions:
    • MaxDepth: Related to folder depth, this condition determines how deep in the navigational tree Skuid will query for folders. The default value is 2.

StaticList

This object represents Marketo lists. Lists provide a way to categorize a Person record, and static lists in particular are created by manually adding or removing persons from that list.

Fields and Conditions

  • Fields: Standard and custom fields are available.
  • No conditions are available for this object.

Channel

While programs represent marketing initiatives, channels segment how persons move through those programs.

Fields and Conditions

  • Fields: Standard and custom fields are available.
  • Conditions:
    • Name: Filter by a channel’s name.

Activity Type

These are the categories of activities that persons can participate in. These are determined within Marketo, and they cannot be created, edited, or filtered. Instead, this object’s main purpose is for cross-referencing with the Activity object—providing practical activity type names for the activities a person participates in.

Fields and Conditions

  • Fields: Standard and custom fields are available.
  • No conditions are available for this object.

Activity

Each activity is an instance of an activity type performed by a person, and the activity log represents how a person may move through a marketing initiative.

Fields and Conditions

  • Fields: Standard activity fields are available, the most important of which are personID and Activity Type ID, which correlate to their respective object’s records.
  • Conditions: Records can be filtered by person, activity type, or date, but both the activityType and dateTime conditions are required.
    • personIDs: The ID of the Person record to filter by. Filter by multiple persons—up to 30—by separating the IDs with commas. E.g. 3,5,9,11
    • activityType (Required): The ID of the activity type to filter by. Filter by multiple activity types—up to 10—by separating the IDs with commas. E.g. 3,5,9,11
    • dateTime (Required): Accepts values in the date literal format, e.g. LASTWEEK, TODAY, LASTN_DAYS:n, etc.

Viewing activity type data [[]]

Because the Activity object only returns the Activity Type ID of an activity, this can lead to unreadable tables of numbers. Not the best user experience!

The solution to this issue is to use a field metadata override and an Activity Type model to display a picklist of human-readable activity type names. To do this:

  1. Create an Activity Type model, which will provide a reference for the activity type IDs.
    • Be sure to include both the id and name fields within this model.
  2. Click the Activity model in the Models tab.
  3. Click the activityTypeId field.
  4. Configure the field’s properties to override the its metadata:
    • Override field metadata: Checked
    • Display type: Picklist
    • Picklist Source: Rows in Model

With the metadata override enabled, you can now set the cross referencing logic:

  1. Click the Picklist Model tab.
  2. Set the following properties:
    • Model: The Activity Type model created in step 1.
    • Entry Value: {{id}}
    • Entry Label: {{name}}
  3. Click Save.

The entry value property tells Skuid to cross reference the activity type ID from the Activity model with the IDs listed in the Activity Type model. Whenever it finds a match, the entry label property instructs Skuid to display the name field instead.

With this override configured, your previously techno-babble activity type ID fields will display which type activity actually occurred. Hooray!

Tag

Tags—through tag types and tag values—are used to categorize and describe programs. This object is read-only.

Fields and Conditions

  • Fields: Standard and custom fields are available.
  • No conditions are available for this object.

Custom Objects

You can also build model on any custom objects within the Marketo instance. These objects are noted by having __c appended to the end of their name.

Fields and Conditions

  • Fields: All fields on custom objects are available.
  • Conditions: Each model attached to a custom object may be filtered using the filterType and filterValues conditions. No other conditions may be created.
    • filterValues: The value(s) to search for within the field selected in the filterType condition.
    • filterType: The field to filter custom object records by.

Data Source Actions

Data source actions on the Marketo data source type allow for the addition and removal of persons from static lists. To obtain values for both the Person ID and List ID properties, you’ll need a model for the Person and StaticList objects—and some savvy use of merge syntax and global merge variables.

  • Add a Person to a Static List: Commonly used as an action within a Person detail page, where the person is fetched by ID.

    Obtaining the proper list ID in this instance requires some extra maneuvering: you’ll also need a StaticList model to obtain list IDs from. One way to do this:

    1. Set an action that opens a popup.
    2. Within that popup, place a Queue or Table component connected to a StaticList model.
    3. Set an interaction or row action to run this data source action and use the following properties:
      • Person ID: {{$Model.PersonById.conditions.0.value}}
      • List ID: {{id}}

    The Person ID obtains the value of the the ID condition on the Person model—as that is the only possible condition when the person is fetched by ID. It then uses the List ID in context to determine which list to add the person to.

    From there, add the standard actions to complete the workflow, such as requerying the appropriate models and closing the popup.

  • Remove a Person from Static List: Commonly used on as a row action on a Person model, where the person is fetched by Static List.

    For example, the following properties would remove a person from the static list that they appear within.

    • Person ID: {{id}}
    • List ID: {{$Model.PersonsByStaticList.conditions.0.value}}

    The List ID obtains the value of the the List condition on the Person model—as that is the only possible condition when the person is fetched by list. It then uses the Person ID in context to determine which person to add to the list.

    From there, add the standard actions to complete the workflow, such as requerying the appropriate models.

Troubleshooting

I receive an “Access token expired” message when updating Marketo models. [[]]

The access token associated with your page visit may have expired. Note and set aside any unsaved changes and then refresh the Skuid page.

I see “Bad request made to Marketo” when trying to select a model entity in the App Composer. [[]]

Double check you have selected an authentication provider for your Marketo data source

End users see “Must query leads using a non-empty condition value” at the top of the Skuid page. [[]]

You may have a model on the Persons object that does not have a list specified in its List condition. Verify that all models attached to the Person object have the List condition set.

End users see “Must have a valid filterType and filterValue condition set” at the top of the Skuid page. [[]]

You may have a model on the a custom object that does not have a its conditions set. Verify that all models attached to custom objects have their filterType and filterValues conditions set.

Adding and removing persons from lists through data source actions does not seem to work. [[]]

Your endpoint URL may be missing its final forward slash /. Double check your Marketo data source.