SFMC Journey Builder

Salesforce Marketing Cloud is a provider of digital marketing automation and analytics software and services.

Enter a customer into a Salesforce Marketing Cloud Journey Builder journey as soon as Amperity sees the customer interaction, by firing the journey’s API entry event. Each real-time point becomes one entry event for one contact. Attributes mapped on the Activate node are sent as the event’s data.

Before it fires the event, Amperity can also insert or update the customer’s row in a data extension that you name. Use this when the journey needs contact data that is not yet in Salesforce Marketing Cloud.

To send a transactional message without a journey, use the SFMC Transactional Messaging connector; to write a data extension row without entering a journey, use the SFMC Data Extension Row connector. To load data extensions on a schedule rather than in real time, use the Salesforce Marketing Cloud destination.

This connector sends from a real-time journey. See Real-time destinations.

Requirements

  1. A journey in Journey Builder whose entry source is an API event. This connector fires the event by its event definition key; it does not create the event or the journey.

  2. When the destination writes to a data extension, that data extension must already exist in Salesforce Marketing Cloud and must have a primary key of one column. Amperity writes the row by one column name and value, so a data extension with a composite primary key cannot be used. This connector does not create data extensions.

  3. An installed package in Salesforce Marketing Cloud with an API integration that issues the client ID and client secret. This connector has no account ID setting, so Amperity does not name a business unit (MID) when it requests an access token, and the token covers the business unit that created the installed package. The journey and the data extension must be in that business unit.

Credentials

This connector uses the same credential type as the SFMC Transactional Messaging and SFMC Data Extension Row connectors. You can reuse one of those credentials here.

Name and description

The name and description for a credential.

API authentication subdomain

The authentication subdomain for your brand’s instance of the Marketing Cloud REST API.

Enter only the subdomain. The form shows “.rest.marketingcloudapis.com” after the field, and Amperity builds both the authentication host and the REST API host from the value you enter.

API client ID and client secret

The client ID and client secret for your brand’s instance of the Marketing Cloud REST API.

Settings

Name and description

The name and description for a destination.

Business user access

By default a destination is available to all users who have permission to view personally identifiable information (PII).

Enable the Admin only checkbox to restrict access to only users assigned to the Datagrid Operator and Datagrid Administrator policies.

Enable the PII setting checkbox to allow limited access to PII for this destination.

Use the Restrict PII access policy option to prevent users from viewing data marked as PII anywhere in Amperity and from sending data to downstream workflows.

Data extension key

Optional. The external key of a data extension to insert or update the customer’s row in before Amperity fires the entry event. Leave this unset to fire the entry event only.

When this is set, every attempt writes the row first. If the row write fails, Amperity does not fire the entry event for that attempt. See Failed sends for which failures get another attempt.

Primary key column name

Optional. The name of the data extension’s primary key column. Defaults to “Contact Key”. Used only when Data extension key is set.

Note

When you save the destination, Amperity tests the connection by checking that the credentials are valid. The test does not check the data extension key or any entry event.

Activate node settings

The rest of the configuration for this connector belongs to the journey that sends to it. Add this destination to an Activate node, then configure the following on that node. Two nodes may send to the same destination with different entry events and custom attributes. Mapped attributes are set once for the destination in the journey, so every node that sends to it uses the same mapped attributes.

event-definition-key

Required. On the Payload tab, the event definition key of the journey’s API entry event. When the error from Salesforce Marketing Cloud says that the event definition was not found, the send fails.

Attribute names

On the Attributes tab, each Amperity attribute is sent under the destination attribute name it is mapped to. Destination attribute names may contain only letters, digits, hyphens, and underscores, and must be unique on the node. Names are matched exactly as written, so map “contact-key” and “primary-key-value” in lowercase. A node needs at least one attribute.

contact-key

Required. Map the Amperity attribute that holds the customer’s contact key in Salesforce Marketing Cloud to contact-key. The node’s attribute editor shows an error when contact-key is not mapped. Amperity sends the value, as mapped, as the contact key of the entry event. When the attribute has no value for a customer, Amperity sends the entry event with a null contact key.

primary-key-value

Optional, and used only when Data extension key is set. Map the Amperity attribute that supplies the value of the data extension’s primary key column. When this is not mapped, or has no value for a customer, Amperity uses the contact-key value. Map an attribute that every customer has: when both are empty, Amperity cannot build the row write, makes no request, and the send fails after three attempts.

The value, or the contact-key value when primary-key-value is not mapped or has no value, must be text. A number or other non-text value also fails every attempt, so the send fails after three attempts and the entry event is never fired.

Event data

Every other attribute mapped on the Attributes tab, and any custom attributes on the same node, is sent as the entry event’s data under the name it is mapped to. A custom attribute with the same name as a mapped attribute replaces it. contact-key and primary-key-value are not part of the event data.

Values are sent as mapped, without changes, with these exceptions:

  • Date values are sent as text in “YYYY-MM-DD” format.

  • Datetime values are sent as text in ISO 8601 format, in UTC.

  • An attribute that is mapped but not on the customer’s profile is left out. An attribute on the profile with no value is sent as null.

Data extension row

When Data extension key is set, Amperity writes one row to that data extension, keyed on the Primary key column name and the primary-key-value (or contact-key) value. The row contains every attribute mapped on the Attributes tab and every custom attribute, as column values under the names they are mapped to, with the same value handling as the event data. This includes a “contact-key” column, and a “primary-key-value” column when that attribute is mapped. Because destination attribute names become column names, a column whose name contains a space cannot be written.

Amperity puts the data extension key, the primary key column name, and the primary key value in the request URL. It replaces spaces in the column name and value with “%20” and encodes nothing else. A space in the data extension key, or a “/”, “?”, “#”, or “%” in the key, column name, or value, can break the request.

Failed sends

Amperity makes up to three attempts at each send. Each attempt writes the data extension row, when Data extension key is set, and then fires the entry event. Within an attempt, Amperity retries each request up to five times, with increasing waits, after a connection error, a request timeout (408), a rate limit error (429), or a server error (5xx). A send can therefore make up to 18 entry event requests, and up to 18 row writes. The entry event carries no key that identifies the send, so each of these requests is a separate entry event.

Amperity paces its requests to Salesforce Marketing Cloud at about one per second for each credential. A send that writes a data extension row makes two requests, so under steady load the destination handles about one such send every two seconds.

Amperity classifies a failure by the text of the error from Salesforce Marketing Cloud first, and then by its HTTP status:

  • The error says “EventDefinitionNotFound”. The send fails without another attempt, with the error from Salesforce Marketing Cloud. Check the event-definition-key.

  • The error says “ObjectNotFound”. The send fails without another attempt, with the error from Salesforce Marketing Cloud, whether the error came from the row write or the entry event. Check the Data extension key and the event-definition-key.

  • The error says “ContactKey”. The send fails without another attempt, with the error from Salesforce Marketing Cloud. Check the attribute mapped to contact-key.

  • 401 or 403. Amperity reports that Salesforce Marketing Cloud rejected the credential. The send fails without another attempt. Check the client ID, client secret, and subdomain. Amperity reuses its connection to Salesforce Marketing Cloud for each credential for up to 20 minutes, so after you edit the credential, sends can keep failing for up to 20 minutes. Choosing a different credential for the destination takes effect at once.

  • 400. The send fails without another attempt. Check the destination’s settings, the event-definition-key, and the attributes mapped on the Activate node.

  • 404, without one of the error texts above. Amperity makes another attempt, up to three in all.

  • Any other failure, including a 429 or server error that persists through the retries, and a connection error such as one caused by a wrong authentication subdomain, gets another attempt, up to three in all.

Amperity reports the send as successful when Salesforce Marketing Cloud accepts the entry event. Amperity does not check whether the contact entered the journey.