Emarsys Events¶

Emarsys is a customer engagement platform that helps marketers deliver personalized engagement across channels.

Trigger an SAP Emarsys external event for a single contact as soon as Amperity sees the customer interaction, using the trigger an external event endpoint. Amperity sends one trigger request for each real-time point, for one contact. The request carries the custom attributes from the Activate node as event data.

The external event is the target of this connector, and each destination triggers one event. To trigger a different event, add another destination. To manage contact lists in SAP Emarsys on a schedule rather than in real time, use the SAP Emarsys destination.

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

Requirements¶

The external event must already exist in SAP Emarsys. See the trigger an external event reference in the SAP Emarsys documentation. This connector triggers an event; it does not create one.
An API user with a client ID and client secret. See API credentials in the SAP Emarsys documentation.
This connector does not create or update contacts. It sends only the contact identifier and the event data.

Credentials¶

This connector uses the “emarsys” credential type, the same type as the SAP Emarsys destination. You can reuse one of those credentials here if its API user may call the endpoints listed below.

Name and description

The name and description for a credential.

Client ID and Client Secret

Required. The OAuth 2.0 client ID and client secret of an API user for your SAP Emarsys account. Amperity exchanges them for an access token.

Amperity calls these SAP Emarsys REST API endpoints, so the API user must be allowed to call them:

POST /api/v3/event/{event ID}/trigger
GET /api/v3/contactlist

Amperity calls GET /api/v3/contactlist only to test the connection when you save the destination. The test does not trigger an event, so it does not check whether the API user may trigger external events.

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.

Event ID

Required. The ID of the external event in SAP Emarsys. This is the event ID, not the event name. Amperity places the value in the request path as entered, and triggers this event for every send to the destination.

Contact identifier

Required. The SAP Emarsys field that Amperity sends as the contact’s key. May be one of the following:

“email” sends “key_id” as “email”, with the value of the mapped attribute named “email”, in lowercase.
“custom_field” sends “key_id” as the Custom field ID, with the value of the mapped attribute that has the same name.

Custom field ID

Required when Contact identifier is “custom_field”. The SAP Emarsys field name or numeric field ID to send as the contact’s key. Amperity also reads the contact’s value from the mapped attribute that has this exact name. For example, with Custom field ID set to “12345”, map the attribute that holds each contact’s value for that field to the name “12345” on the Attributes tab of each Activate node.

Attribute names on the Attributes tab may contain only letters, numbers, hyphens, and underscores. A field name that contains other characters, such as a space, cannot be matched to an attribute; use the field’s numeric ID instead.

The destination saves without this setting. The check runs on each Activate node that sends to the destination: its attributes show an error until Custom field ID is set.

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 fields on that node. The event is set on the destination, so every node that sends to the same destination triggers the same event.

Attributes

Map the attribute that holds the contact identifier: “email”, or the attribute named after the Custom field ID. The Activate node does not require this mapping. Amperity sends the value as mapped, without changing or validating it, and does not check that it has a value before sending. When the attribute is not mapped or has no value, the request’s “external_id” is null.

Attribute names on the Attributes tab may contain only letters, numbers, hyphens, and underscores, must be unique, and cannot be blank. Each node must have at least one attribute enabled.

Amperity sends only the contact identifier from the Attributes tab. Other attributes mapped there are not sent to SAP Emarsys.

Custom attributes

Attributes added on the Custom attributes tab are sent in the request’s “data.global” object, using their names. When a node has no custom attributes, the request has no “data” object.

Request body¶

For example, with Contact identifier set to “email” and a custom attribute named “basket_value”, Amperity sends:

{
  "key_id": "email",
  "contacts": [
    {
      "external_id": "customer@example.com",
      "trigger_id": "...",
      "data": {
        "global": {
          "basket_value": "49.99"
        }
      }
    }
  ]
}

The “trigger_id” identifies the send, and Amperity sends the same “trigger_id” in every request for that send, including retries. When SAP Emarsys responds that a trigger with that “trigger_id” was already processed, Amperity counts the send as successful.

Failed sends¶

Amperity makes up to three attempts at each send. Within an attempt, Amperity retries the 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). One send can therefore make up to 18 requests, all with the same “trigger_id”.

How Amperity handles each failure:

429 or server error (5xx) that persists through the retries within an attempt. Amperity makes another attempt, up to three in all.
Connection error or request timeout (408) that persists through the retries within an attempt. The send fails without another attempt.
401 or 403. The send fails without another attempt. The error says that authentication failed. Check the client ID and client secret.
400. The send fails without another attempt. The error gives only the HTTP status, so check the Event ID, the Contact identifier, and the attributes mapped on the Activate node.
Any other HTTP error. The send fails without another attempt.

When the response is not an HTTP error (its status is below 400), Amperity reads the reply code in the response body. The send succeeds only when the reply code reports success, or reports that the “trigger_id” was already processed. A missing reply code, or any other reply code, fails the send without another attempt. For these reply codes, the error names the cause:

The Contact identifier or Custom field ID is not a valid key field.
The contact identifier value is missing or not valid.
No contact matches the contact identifier.
More than one contact matches the contact identifier.

Choose topic collections