> For the complete documentation index, see [llms.txt](https://docs.thewalletcrew.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.thewalletcrew.io/developers-guides/scripting/extensions/bloomreach.md).

# Bloomreach scripts

Reference of the three Bloomreach scripts, contact finder, event interceptor and customer mapper: registration, handlers, sync rules and examples.

Three scripts adjust the Bloomreach connector: the contact finder decides which Bloomreach contact a pass belongs to, the event interceptor renames, changes or drops the events sent to Bloomreach, and the customer mapper maps fields between the wallet account and Bloomreach. This page is the reference for `extensions.bloomreach.contact.finder`, `extensions.bloomreach.event.interceptor` and `extensions.bloomreach.customer.mapper`. Setup and rollout are on the [Bloomreach extensibility page](https://docs.thewalletcrew.io/connectors/marketing-automation/bloomreach/extensibility.md) of the connector; the rules shared by every connector script are in [Connector scripts](https://docs.thewalletcrew.io/developers-guides/scripting/extensions.md).

<details>

<summary><strong>Real-world examples</strong></summary>

* A brand identifies its Bloomreach contacts by member id and resolves the member id of a pass into the email Bloomreach knows.
* A brand renames the wallet events to its own naming convention and drops the events of test passes.
* A brand aligns the names of the Bloomreach properties with its pass templates.

</details>

## Registration

| Key                                       | Slot file                         | Methods (required in **bold**)                     | Sync or async                        |
| ----------------------------------------- | --------------------------------- | -------------------------------------------------- | ------------------------------------ |
| `extensions.bloomreach.contact.finder`    | `bloomreach.contact.finder.js`    | **`GetContactIdentifiers`**, `Describe`            | Asynchronous; `Describe` synchronous |
| `extensions.bloomreach.event.interceptor` | `bloomreach.event.interceptor.js` | **`Intercept`**                                    | **Synchronous**                      |
| `extensions.bloomreach.customer.mapper`   | `bloomreach.customer.mapper.js`   | `MapToBloomreach`, `MapFromBloomreach`, `Describe` | Synchronous                          |

Each key has its own slot in the **Advanced** tab of the Bloomreach connector, and the slots are read and written with `GET` and `PUT /api/{tenantId}/admin/extensions/bloomreach/scripts`. When no script is registered for a key, the default behavior applies, described with each script below.

## When it runs

| Script            | Runs                                                                                                                                                                                             |
| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Contact finder    | When the Bloomreach customer of a pass is read and when a pass event is sent to Bloomreach. The `bloomreachCustomer` registration step does not use it: it always looks the customer up by email |
| Event interceptor | Before an event is sent to Bloomreach                                                                                                                                                            |
| Customer mapper   | When Bloomreach data is read for a pass (the `bloomreach` customer provider) and when a customer is written by the `bloomreachCustomer` registration flow step                                   |

The customer mapper is not used by every Bloomreach activity: sending a notification does not need it.

## Contact finder

`GetContactIdentifiers(identifiers)` receives the identifiers of the pass and returns the Bloomreach identifiers of the contact, keyed by identifier type. The key `registered` holds the identifier Bloomreach uses to recognize the contact.

* Without a script, a pass with an `email` identifier is looked up as `{ registered: email }` only, and its other identifiers are dropped; a pass without `email` is looked up with its identifiers unchanged.
* The method is asynchronous, so it can call an external service with [fetch](https://docs.thewalletcrew.io/developers-guides/scripting/globals/fetch.md).
* An optional `Describe()` returns `{ identifiers: [{ key }] }`, so that the admin console can list the identifiers before any pass carries them.

## Event interceptor

`Intercept(eventData)` receives `{ Name, Properties }` (PascalCase) and returns the event to send.

* `Name` cannot be changed on the received object: return a new `{ Name, Properties }` to rename the event. The properties of the received object can be changed in place and the object returned.
* Return `null` to drop the event. Nothing is sent, and the skip is logged at debug level.
* Property values are strings. A property set to `null` is left out of the event.
* The method is **synchronous**. An `async` function returns a promise, which the connector cannot use.
* A throw in `Intercept` is not caught: it fails the sending of that event.

## Customer mapper

All methods are optional.

* `MapToBloomreach(account, properties)` fills the `properties` dictionary before the customer is created or updated in Bloomreach (the `UpsertCustomer` call of the registration flow step). It changes `properties` in place.
* `MapFromBloomreach(customer, account)` receives the Bloomreach customer, with `customer.Identifiers` (each key to a list of strings) and `customer.Properties` (each key to a value), and fills `account` in place.
* `Describe()` returns `{ fields: [{ path, description }] }`, so that the admin console can list the fields.

`account` is the flat wallet account (see [Data objects](https://docs.thewalletcrew.io/developers-guides/scripting/data-objects.md)), with camelCase keys such as `firstName`. `customer.Properties` and `eventData.Name` are PascalCase members of Bloomreach objects.

## Errors and edge cases

* **No script registered**: the default behavior of each script applies.
* **A required method is missing**: the call fails with `method <Name> missing` when the connector reaches it.
* **A returned member has the wrong case** (`name` instead of `Name`): it is ignored.
* **A script throws**: the error reaches the connector operation that called it.

## Example

The three scripts below belong in three files, one for each key.

The contact finder resolves a member id into the email Bloomreach knows, and falls back to the email of the pass:

```js
async function getContactIdentifiers(identifiers) {
  const email = identifiers['email'];
  if (email) {
    return { registered: email };
  }
  const memberId = identifiers['crm.customerId'];
  if (!memberId) {
    return {};
  }
  const response = await fetch(`https://crm.example.com/api/members/${encodeURIComponent(memberId)}`, {
    ThrowOnError: false,
    Cache: { CacheKey: `bloomreach-contact|${memberId}`, DurationInMs: 10 * 60 * 1000 }
  });
  if (response.StatusCode !== 200 || !response.ResponseText) {
    return {};
  }
  const member = JSON.parse(response.ResponseText);
  return member.email ? { registered: member.email } : {};
}

export default function (context) {
  context.register('extensions.bloomreach.contact.finder', {
    GetContactIdentifiers: getContactIdentifiers
  });
}
```

The event interceptor drops scan events and prefixes the other event names. It is a plain function, not an `async` one:

```js
function intercept({ Name, Properties }) {
  if (Name === 'scan') {
    return null;
  }
  return { Name: `wallet_${Name}`, Properties };
}

export default function (context) {
  context.register('extensions.bloomreach.event.interceptor', {
    Intercept: intercept
  });
}
```

The customer mapper copies two names in each direction and writes only the values that exist:

```js
function mapToBloomreach(account, properties) {
  if (account['firstName']) {
    properties['first_name'] = account['firstName'];
  }
  if (account['lastName']) {
    properties['last_name'] = account['lastName'];
  }
}

function mapFromBloomreach(customer, account) {
  const properties = customer?.Properties;
  if (properties?.['first_name']) {
    account['firstName'] = properties['first_name'];
  }
  if (properties?.['last_name']) {
    account['lastName'] = properties['last_name'];
  }
}

export default function (context) {
  context.register('extensions.bloomreach.customer.mapper', {
    MapToBloomreach: mapToBloomreach,
    MapFromBloomreach: mapFromBloomreach
  });
}
```

## Common pitfalls

* The interceptor is written as an `async` function: the connector receives a promise instead of an event.
* The interceptor changes `Name` on the received object instead of returning a new `{ Name, Properties }`.
* The contact finder calls a remote service on every event without a `Cache`.
* The properties are named in the script with other names than in Bloomreach, so the values land in new properties.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.thewalletcrew.io/developers-guides/scripting/extensions/bloomreach.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
