Send query results to Bloomreach

Bloomreach Engagement (formerly Exponea) is a customer data and marketing automation platform. Use Bloomreach Engagement to create personalized customer experiences across multiple channels.

This destination uses the Bloomreach Engagement API .

Important

Amperity sends segment membership to Bloomreach Engagement in one of two ways, depending on the credential.

• As an external segment, when the credential has an External segments integration. Amperity registers the segment in Bloomreach Engagement under the Segment name, and then adds and removes customers as their membership changes. The segment appears in Bloomreach Engagement under Analyses > External segments and is stored on each customer profile as the boolean property ext_segment_<name>: true while the customer is in the segment, and false after the customer leaves it. The segment is ready to use in Bloomreach Engagement without further setup. Depending on how the integration is configured, a customer ID that matches no profile either creates a profile or is ignored. External segment membership updates count against your Bloomreach Engagement project’s monthly customer update limits.

• As segment membership events, when the credential has no External segments integration. Amperity records each change as an amperity-segment event whose segment_name property holds the segment name and whose action property is addition or deletion. To act on this membership in Bloomreach Engagement (for example, to target it in a campaign), build a segmentation in your Bloomreach Engagement project over these events. Until that segmentation exists, the membership data is present in Bloomreach Engagement but is not usable as a segment.

The steps that are required to send customer profiles to Bloomreach Engagement from Amperity.

	Build a query
	Add orchestration
	Run orchestration

Caution

This destination is available for sending query results to Bloomreach Engagement 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 Bloomreach Engagement.

Build query

You will need to build a query that outputs the fields you want to send to Bloomreach Engagement. The query must include a Bloomreach hard identifier such as email, external ID, cookie, or Google Analytics ID. All other columns in your query results will be sent as customer properties.

The following example shows a query that returns customer profiles using email as the identifier:

SELECT
  email
  ,given_name
  ,surname
  ,city
  ,state
  ,postal
  ,birthdate
  ,gender
FROM Customer360
WHERE email IS NOT NULL

You can also use the Amperity ID as an external identifier:

SELECT
  amperity_id AS external_id
  ,email
  ,given_name
  ,surname
  ,phone
  ,lifetime_order_revenue
  ,lifetime_order_frequency
FROM Customer360
WHERE amperity_id IS NOT NULL

Important

Your query results must include a column named to match the Bloomreach identifier selected for the destination (for example, a column named email when the identifier is email). If no column matches, the orchestration fails with an error before any data is sent. Rows with blank values in the identity column are skipped, counted as failed rows, and reported as an error on the run in Amperity.

Caution

Bloomreach Engagement limits the number of distinct attributes in a project (255 by default, though this may vary based on your Bloomreach Engagement contract). An orchestration or campaign whose query or segment has more attributes than the limit fails with an error before any data is sent. When segment membership is sent as an external segment, Amperity reserves one attribute for the segment’s ext_segment_<name> property, so the query or segment may contain at most 254 attributes.

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 Bloomreach Engagement.

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

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.

To run the orchestration

1. Open the Activations page, select the Orchestrations tab, and then open the menu for the Bloomreach Engagement 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”.

Note

Amperity sends only what changed since the previous run. For each run, Amperity chooses how to send each lane of data–customer attribute updates and segment membership changes are separate lanes–based on how many rows that lane contains:

• Up to 500,000 rows in a lane are sent over the Bloomreach Engagement batch API, and Amperity receives a result for each row in the same request. Rows that Bloomreach Engagement rejects are reported as failed, and the rejection reason is recorded as an error on the orchestration or campaign run in Amperity.

• More than 500,000 rows in a lane are sent over the Bloomreach Engagement Imports API as one bulk file. Bloomreach Engagement accepts each import and processes it afterward, and does not return per-row results. The run reports success when Bloomreach Engagement accepts the import, not when its rows finish processing. Import outcomes surface only in Bloomreach Engagement: in the import history in the Bloomreach Engagement console (retained for 30 days) and in ImportError and ImportRowsDiscarded notifications to project users. Because processing is progressive, an import that fails partway may leave rows partly applied.

The two lanes cross this threshold independently, so a single run may use the batch API for one lane and the Imports API for the other.

When segment membership is sent as an external segment, the membership lane never uses the Imports API, however many rows it contains. Amperity sends additions and removals in requests of up to 5,000 customer IDs and receives a result for each customer ID. Customer IDs that Bloomreach Engagement rejects (for example, an ID longer than 256 bytes) and audience members with no value for the Bloomreach identifier are counted as failed membership changes and reported as errors on the run, with a count for each reason. The first run that sends a segment as an external segment, including the first run after an External segments integration is added to the credential, sends every member of the audience, even if the audience has not changed. Bloomreach Engagement accepts about 1,000 customer IDs per second for external segment updates, so a large first load takes time: about 19 minutes per million members.

Warning

Attributes accumulate across everything sent to a Bloomreach Engagement project over time, and the attribute limit applies to the project’s total number of distinct attributes, not to each customer profile. Each external segment also uses one of these attributes. Once the project is at the limit:

• An update that would add a new attribute is discarded as a whole. Over the batch API (up to 500,000 rows), Bloomreach Engagement accepts the update and returns no error, so the run reports these rows as succeeded. Over the Imports API, the failure surfaces only in Bloomreach Engagement’s import history and notifications, as described above.

• Registering a new external segment fails, and the run stops with an error saying that the Bloomreach Engagement project has no room for another external segment.

Updates to attributes the project already has are not affected. To make room, remove unused attributes or external segments in Bloomreach Engagement, or ask Bloomreach Engagement to raise the limit.