Configure destinations for Bloomreach

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

Use Amperity to manage customer profiles in Bloomreach Engagement. Build a query or segment, and then send customer data to Bloomreach Engagement for segmentation, campaigns, and personalization. Customer profiles are identified by a Bloomreach hard identifier such as email, cookie, Google Analytics ID, or external ID. If a matching customer profile does not already exist in Bloomreach Engagement, Amperity creates it.

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.

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.

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.

Get details

Review the following details before configuring credentials for Bloomreach Engagement and before configuring Amperity to send customer profiles to Bloomreach Engagement.

	Credential settings API base URL Required The API base URL for your Bloomreach Engagement project. Project token Required The project token for your Bloomreach Engagement project. API key ID Required The public API key ID for your Bloomreach Engagement project. API secret Required The private API secret for your Bloomreach Engagement project. The API key’s API group must permit customer updates, event tracking, and imports–under Imports, both Allow to Create new Imports and the delete permission. Import permissions are used only when a run exceeds the bulk threshold, so a key that lacks them still passes the connection test and works until the first large run. You can find the API base URL and project token in your Bloomreach Engagement project settings. The API key ID and API secret are available in the API access section of your project settings. External segments integration ID The integration ID of an External segments integration in your Bloomreach Engagement project. When the integration ID and access key are both set, Amperity sends segment membership as a Bloomreach external segment instead of as segment membership events. Enter both values, or leave both empty to send segment membership events. External segments access key The access key of the External segments integration. Bloomreach Engagement shows the access key only once, when the integration is created. Required when an integration ID is entered. To create an External segments integration, open Data & Assets > Integrations in your Bloomreach Engagement project, click + Add new integration, and select External segments. Select the hard identifier that incoming customer IDs are matched on. This must be the identifier entered as the Bloomreach identifier on every destination that uses this credential, because membership is keyed on that identifier and Bloomreach Engagement does not report which identifier an integration uses. Click Create integration, and then copy the integration ID and the access key. The integration must belong to the same project as the API base URL. An integration from another project fails the connection test. If External segments is not offered in your project, contact your Bloomreach Customer Success Manager.
	Required configuration settings Bloomreach identifier Required The Bloomreach hard identifier to use as the primary key. Enter the name exactly as one of the hard identifiers defined for your Bloomreach project (under Administration > Identifiers). Map a dataset attribute to a destination attribute with the same name as the identifier you enter. If no dataset attribute matches, the run fails with an error before any data is sent. The list of hard and soft identifiers is project-dependent; for your project’s identifier lists, contact your Bloomreach CSM. Additional identifiers A list of other Bloomreach hard or soft identifiers to key your data with, entered as comma-separated values (for example, cookie,google_analytics). Name each one exactly as it is defined for your Bloomreach project. Map a dataset attribute to a destination attribute with the same name as each identifier in the list. If a dataset attribute does not match a listed identifier, the run fails with an error before any data is sent. Each additional identifier is sent as identity data, not as a customer attribute: attribute updates carry these identifiers, but segment membership is always keyed on the primary Bloomreach identifier alone. The list of hard and soft identifiers is project-dependent; for your project’s identifier lists, contact your Bloomreach CSM. Segment name Required A name for the segment sent to Bloomreach. When the credential has an External segments integration, Amperity registers an external segment with this name the first time it sends the segment. Bloomreach stores membership in the customer property ext_segment_<name>, normalizing the name for the property: periods, dollar signs, null characters, and hyphens become underscores, so vip-gold is stored as ext_segment_vip_gold. The normalized name can be at most 243 characters. Changing the name starts a new external segment. The old segment and its property remain in Bloomreach until you remove them there. If a segment with this name is already registered on the integration, but not by Amperity, the run fails with an error that asks you to rename the segment. When the credential has no External segments integration, Amperity records each membership change as an amperity-segment event, with this name in the event’s segment_name property and addition or deletion in its action property.
	A query that outputs the fields that must be sent to the Bloomreach Engagement customer table.

Configure credentials

Configure credentials for Bloomreach Engagement before adding a destination.

An individual with access to Bloomreach Engagement should use SnapPass to securely share “API base URL”, “Project token”, “API key ID”, and “API secret” details with the individual who configures Amperity.

To configure credentials for Bloomreach

	From the Settings page, select the Credentials tab, and then click the Add credential button.
	In the Create credential dialog box, do the following: From the Plugin dropdown, select “Bloomreach”. Assign the credential a name and description that ensures other users of Amperity can recognize when to use this destination.
	The settings that are available for a credential vary by credential type. For the “bloomreach” credential type, configure settings, and then click Save. API base URL Required The API base URL for your Bloomreach Engagement project. Project token Required The project token for your Bloomreach Engagement project. API key ID Required The public API key ID for your Bloomreach Engagement project. API secret Required The private API secret for your Bloomreach Engagement project. The API key’s API group must permit customer updates, event tracking, and imports–under Imports, both Allow to Create new Imports and the delete permission. Import permissions are used only when a run exceeds the bulk threshold, so a key that lacks them still passes the connection test and works until the first large run. You can find the API base URL and project token in your Bloomreach Engagement project settings. The API key ID and API secret are available in the API access section of your project settings. External segments integration ID The integration ID of an External segments integration in your Bloomreach Engagement project. When the integration ID and access key are both set, Amperity sends segment membership as a Bloomreach external segment instead of as segment membership events. Enter both values, or leave both empty to send segment membership events. External segments access key The access key of the External segments integration. Bloomreach Engagement shows the access key only once, when the integration is created. Required when an integration ID is entered. To create an External segments integration, open Data & Assets > Integrations in your Bloomreach Engagement project, click + Add new integration, and select External segments. Select the hard identifier that incoming customer IDs are matched on. This must be the identifier entered as the Bloomreach identifier on every destination that uses this credential, because membership is keyed on that identifier and Bloomreach Engagement does not report which identifier an integration uses. Click Create integration, and then copy the integration ID and the access key. The integration must belong to the same project as the API base URL. An integration from another project fails the connection test. If External segments is not offered in your project, contact your Bloomreach Customer Success Manager.

Add destination

Use a sandbox to configure a destination for Bloomreach Engagement. Before promoting your changes, send a sample audience, and then verify the results in Bloomreach Engagement. After verifying the end-to-end workflow, push the destination from the sandbox to production.

To add a destination for Bloomreach

	Open the Destinations page, select the New destinations button, and then select Orchestration. To configure a destination for Bloomreach Engagement, do one of the following: Click the row in which Bloomreach Engagement is located. Destinations list alphabetically and you can scroll up and down the list. Search for Bloomreach Engagement. Start typing “blo”. The list filters to show only matching destinations. Select “Bloomreach”.
	Select the credential for Bloomreach Engagement from the Credential dropdown, and then click Continue. Tip Amperity validates the connection when the destination is saved. If the connection cannot be validated, an error is shown and the destination is not saved.
	In the “Destination settings” dialog box, assign the destination a name and description that ensures other users of Amperity can recognize when to use this destination. Configure 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.
	Configure the following settings, and then click “Save”. Bloomreach identifier The Bloomreach hard identifier to use as the primary key. Enter the name exactly as one of the hard identifiers defined for your Bloomreach project (under Administration > Identifiers). Map a dataset attribute to a destination attribute with the same name as the identifier you enter. If no dataset attribute matches, the run fails with an error before any data is sent. The list of hard and soft identifiers is project-dependent; for your project’s identifier lists, contact your Bloomreach CSM. Additional identifiers A list of other Bloomreach hard or soft identifiers to key your data with, entered as comma-separated values (for example, cookie,google_analytics). Name each one exactly as it is defined for your Bloomreach project. Map a dataset attribute to a destination attribute with the same name as each identifier in the list. If a dataset attribute does not match a listed identifier, the run fails with an error before any data is sent. Each additional identifier is sent as identity data, not as a customer attribute: attribute updates carry these identifiers, but segment membership is always keyed on the primary Bloomreach identifier alone. The list of hard and soft identifiers is project-dependent; for your project’s identifier lists, contact your Bloomreach CSM. Segment name A name for the segment sent to Bloomreach. When the credential has an External segments integration, Amperity registers an external segment with this name the first time it sends the segment. Bloomreach stores membership in the customer property ext_segment_<name>, normalizing the name for the property: periods, dollar signs, null characters, and hyphens become underscores, so vip-gold is stored as ext_segment_vip_gold. The normalized name can be at most 243 characters. Changing the name starts a new external segment. The old segment and its property remain in Bloomreach until you remove them there. If a segment with this name is already registered on the integration, but not by Amperity, the run fails with an error that asks you to rename the segment. When the credential has no External segments integration, Amperity records each membership change as an amperity-segment event, with this name in the event’s segment_name property and addition or deletion in its action property.
	After configuring this destination users may use: Orchestrations to send query results Orchestrations and campaigns to send audiences
	Validate the audience with Bloomreach Engagement by using a sample audience with a very small membership. For example: 10 or 100 members or the minimum audience size recommended by Bloomreach Engagement. Send the sample audience to Bloomreach Engagement and verify the sample audience is correct in Bloomreach Engagement. Make adjustments if necessary. Only send full audiences after validation is complete.