Send query results to MoEngage Attributes

MoEngage is a cross-channel customer engagement platform built for marketers and product owners who value agility over complexity. Use real-time insights and personalized cross-channel communications and adapt to evolving customer expectations.

Note

This destination uses the MoEngage Data API , sending users with Bulk Import .

Beta

The MoEngage Attributes connector is in beta. Contact your Amperity representative to learn more.

The steps that are required to send customer attributes to MoEngage from Amperity.

Caution

This destination is available for sending query results to MoEngage after it is configured by a Datagrid Operator or your Amperity representative.

If this destination cannot be selected for orchestrations ask your Datagrid Operator or Amperity representative to configure a destination for sending query results to MoEngage.

Build query

Build a query that returns a customer_id field and one field for each attribute that you want to send. Each row is one user. Amperity sends every field other than customer_id as a user attribute named after the field.

The following example returns the email address, first name, and last name from the Customer 360 table, named with the MoEngage keys for those standard attributes. Replace app_user_id with the field in your tenant that holds the ID your app or website uses for each user in MoEngage:

SELECT
  app_user_id AS customer_id
  ,email AS u_em
  ,given_name AS u_fn
  ,surname AS u_ln
FROM Customer_360
WHERE app_user_id IS NOT NULL

Each run sends only the rows that changed since the last successful run.

The customer ID is the unique ID that MoEngage identifies a user by. It is usually the ID that your app or website passes to the MoEngage SDK when a user logs in, which is not necessarily the Amperity ID. Confirm which field in Amperity holds the same value before you send, and alias that field as customer_id in the query, for example SELECT loyalty_id AS customer_id.

Amperity sends each customer ID as text, after removing leading and trailing whitespace, and MoEngage matches it exactly. When the field holds a floating-point number, such as a DOUBLE, or a DECIMAL with digits after the decimal point, convert it in the query, for example CAST(CAST(loyalty_id AS BIGINT) AS VARCHAR) AS customer_id. Otherwise the ID 12345 is sent as 12345.0 or 12345.00 and does not match the user in MoEngage.

Return one row for each customer ID. Amperity does not send these rows:

  • A row whose customer ID is null or empty. Amperity skips the row without an error, and counts it with the rows sent from cache.

  • A row whose customer ID repeats another row’s customer ID. Amperity keeps one of the rows and skips the others without an error. Which row it keeps is not determined.

  • A row whose customer ID MoEngage does not accept. This is a customer ID that contains only whitespace, is one character long, or is a placeholder value such as unknown, guest, null, none, n/a, 0, or -1. These values are compared without regard to case. MoEngage lists the values it does not accept in its Data API overview . Amperity reports the row as failed instead of sending it.

User attributes

Every column in the query results except customer_id is sent to MoEngage as a user attribute. The column name becomes the attribute name, and the column value becomes the attribute value.

  • Standard attributes need MoEngage’s attribute names. To fill a standard MoEngage attribute, name the column with that attribute’s key, for example SELECT email AS u_em. A column with any other name creates or updates a custom attribute with that name.

    Column name

    Standard attribute

    u_em

    Email

    u_mb

    Mobile number

    u_fn

    First name

    u_ln

    Last name

    u_n

    Full name

    u_gd

    Gender

    u_bd

    Birthdate

    MoEngage lists every standard attribute and its format in the Bulk Import reference.

  • Values are sent as your query returns them. Amperity does not convert or check attribute values. A number is sent as a number, a Boolean value as a Boolean value, and text as text. Build the exact value that you want to see in MoEngage in your query.

  • Send dates as ISO 8601 text. MoEngage documents date attributes, including u_bd, in ISO 8601 format with a time and a time zone, for example 2020-05-31T03:47:35Z. Amperity sends a date the way the query returns it, so convert a date that is in another form, such as 05/31/2020 or a number of seconds since 1970, in the query. To convert a timestamp that is in UTC, use DATE_FORMAT(birthdate, '%Y-%m-%dT%H:%i:%sZ') AS u_bd.

  • A null value clears the attribute. When a column is null for a row, Amperity asks MoEngage to remove that attribute from the user, so that MoEngage matches Amperity. This also clears a value that another source, such as a MoEngage SDK in your app or website, set for that attribute. A column that is empty text, rather than null, is sent as empty text.

  • Some attribute names are not accepted. MoEngage does not accept id, _id, or an empty name as an attribute name. A send whose query results have a column with one of these names fails before any data is sent. Rename the column.

Caution

MoEngage reserves the moe_ prefix for its own attributes, and says that it can block a workspace that uses the prefix for custom attributes. Amperity does not check for the prefix, because some standard attributes, such as moe_unsubscribe, use it. Name a column with moe_ only when it fills a MoEngage standard attribute.

Caution

Amperity owns the attributes that it sends. When a row changes, Amperity sends all of the row’s attributes, which overwrites the values that another source, such as a MoEngage SDK, set for the same attributes. Do not send an attribute that another source should own.

Caution

Amperity sends only the rows that are in the query results. A user who drops out of the query results is not sent again, so the attributes that user already has stay in MoEngage, holding their last values. Removing a column from the query has the same effect: the attribute keeps its last value on every user who has it.

To clear an attribute for users who no longer qualify, keep them in the query results and return a null value for that attribute.

Add orchestration

An orchestration defines the relationship between query results and a destination, including the destination and the frequency at which an orchestration runs.

  1. Open the Activations page, select the Orchestrations tab, and then click the Add orchestration button. This opens the Add orchestration dialog box.

  2. From the Object type dropdown, select Query.

  3. From the Object dropdown, select the query for which results is sent to MoEngage.

  4. From the Destination dropdown, select a destination that is configured for sending data to MoEngage.

  5. Verify all settings.

  6. Set the workflow to Manual. You can change this to automatic later, after verifying the end-to-end workflow.

  7. Click Save.

Run orchestration

Run the orchestration manually to validate that it works.

  1. Open the Activations page, select the Orchestrations tab, and then open the menu for the MoEngage orchestration. Select Run.

  2. The Status column for the orchestration updates to say “Waiting to start”, after which the notifications pane updates to include a notification that shows the current status.

  3. When the orchestration has run successfully, the status is updated to “Completed”.