Marketo Output Tool (SOAP API)

The Marketo Output tool (SOAP API) has been deprecated. The Marketo Output tool (REST API) replaces this tool.

The Marketo Output tool calls to the Marketo API function: syncLead(). Data is written back to Marketo using an 'Upsert' operation. This means if a record doesn't currently exist, it will be created (see 'Inserts' below). If a record currently exists, it will be updated (see 'Updates' below).

Inserts

Inserts can be done by specifying any field at all. You do not have to supply email address or any of the other 4 fields used as unique identifiers (Email, ForeignSysPersonID or Cookie). A Marketo ID is generated when a new record is inserted and that can be used as a unique identifier in the absence of the others. Therefore, the minimum requirement to insert a new record is to specify *any* field.

Updates

In order to update a Lead in Marketo you must supply a unique identifier.

When updating an existing lead, the lead can be identified by any of the following:

Marketo ID

This is the internal Marketo ID that each Lead record has

Foreign System ID

This is required if no Email Address or Marketo ID is supplied. You can update the ForeignSysPersonID value by also supplying the Marketo ID. See the precedence rules below

Marketo Cookie

A web form cookie can be used to uniquely identify a Lead

Email

Email address can be changed if you supply a Marketo ID, which takes precedence. Otherwise, if only an email address is supplied, it will be used as a unique identifier.

It is possible to have records in Marketo with the same email address. In this case, an update will only operate on the first record with the supplied email address. This may result in unexpected behavior - the record updated may not be the one you expected.

 

Configure the tool

API Access in Marketo must be enabled to use this tool. The Endpoint, User ID, and Encryption key can be found in Marketo by going to Admin > Integration > SOAP API.

  1. Marketo SOAP API Endpoint (URL): Marketo location to write the data to. This information is found in Marketo (Admin > Integration > SOAP API).
  2. Marketo User ID: User credential for Marketo access. This information is found in Marketo (Admin > Integration > SOAP API).
  3. Marketo Encryption Key: Additional credential supplied by Marketo. This information is found in Marketo (Admin > Integration > SOAP API).
  4. Save Connection History: when checked, the first 3 configuration settings will be saved and automatically populated each time the tool is used. If multiple Endpoints are used, each one will be available from the Endpoint dropdown list.
  5. Target Workspace: The Target Workspace is only available in Enterprise Edition and if Workspaces are enabled. Otherwise the only Workspace available is the "Default" Workspace.
    • If you leave the configuration property field blank, Alteryx will send requests to Marketo without specifying a ContextHeader element. This results in the Default Workspace being used.  If you specify a Target Workspace of "Default", Alteryx will construct a ContextHeader and populate it with a Target Workspace of "Default". This will work just fine, but is not required.
    • Specifying the Workspace name in the Target Workspace field will result in the ContextHeader construction using the specified Workspace. The resulting Insert/Update will be directed to the specified Workspace.

Data Considerations

You want to make sure to maintain Marketo datatypes and field structures in Alteryx, before writing back to Marketo to avoid errors. Some common errors you may see from Alteryx when writing to Marketo include:

  • Invalid value (can’t be converted to destination datatype)
  • Invalid field name (does not exist in Marketo)
  • If a SOAP error occurs, it will be written to the Alteryx log.

Datetime fields

All dates in Marketo are stored with a UTC offset. This format is comprised of the local time with an appended offset that can be positive or negative. For example, a datetime value in Marketo might look like this:

2012-02-28T14:00:00-06:00 where the date inserted into Marketo is from a timezone that is 6 hours earlier than UTC time (Mountain Daylight Time).

ForeignSysPersonId and ForeignSysType:

There are two fields in Marketo that are used to hold UserIDs from foreign (external) systems such as SalesForce.com (SFDC) and NetSuite.

ForeignSysPersonId

Holds the ID from the external system, such as SalesForce.com (SFDC)

ForeignSysType

This must be SFDC, NETSUITE, or CUSTOM

The challenge with these fields is that while you can insert data into them, and even use the ForeignSysPersonId values as unique identifiers, you cannot retrieve this data from Marketo. For example, you could create a new Lead in Marketo where you specify an SFDC User ID as the ForeignSysPersonId and "SFDC" as the ForeignSysType and the Lead would be created. The SFDC User ID would be populated into the Marketo field correctly, however when you read the Lead back out of Marketo, both ForeignSysPersonId and ForeignSysType will always be returned as NULLs.

This is explained in the Marketo API documentation like this:

At present, ForeignSysPersonId is never returned in getLead or getMultipleLeads operations, so you cannot read this value through the API . You can set those ForeignSys field values with a syncLead, and you can then reference leads with that stored ForeignSysPersonId.

It does work to send update requests, using the ForeignSysPersonId as the unique identifier, and it will work. However, you have to know which record has your ForeignSysPersonId value since you can not determine this through a call to getLead() - which can be accomplished with the Alteryx Marketo Join Tool.