> 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/cegid-ur.md).

# Cegid UR scripts

Reference of the Cegid UR customer mapper and connection interceptor scripts: registration without a slot, handlers and an authentication example.

Two scripts adjust the Cegid UR connector. The mapper maps customer data between Cegid UR and the wallet account. The connection interceptor sees every SOAP call the connector makes and can add the authentication header, because the connector configuration holds no credential. This page is the reference for `extensions.cegid.ur.mapper` and `extensions.cegid.ur.connectionInterceptor`. The connector is described on the [Cegid UR connector page](https://docs.thewalletcrew.io/connectors/pos/cegid/cegid-ur.md); the rules shared by every connector script are in [Connector scripts](https://docs.thewalletcrew.io/developers-guides/scripting/extensions.md). Cegid UR is a different connector from [Cegid Y2](https://docs.thewalletcrew.io/developers-guides/scripting/extensions/cegid-y2.md), with different member names.

<details>

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

* A brand sends the key stored in its secrets as an authentication header on every call to Cegid UR.

</details>

## Registration

| Key                                         | Methods (required in **bold**)              |
| ------------------------------------------- | ------------------------------------------- |
| `extensions.cegid.ur.mapper`                | `MapFromUR`, `MapToUR`                      |
| `extensions.cegid.ur.connectionInterceptor` | **`OnBeforeRequest`**, **`OnAfterRequest`** |

Cegid UR has no script slot and no slot API. The scripts are ordinary files under `server/scripts/`, with any name, edited in the advanced configuration. When no script is registered for a key, the default behavior applies.

## When it runs

| Script      | Runs                                                                                                                                                                                                 |
| ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `MapFromUR` | At the end of the customer read (the `ur.customer` customer provider), after the standard mapping has written `firstName`, `lastName`, `email`, `loyaltyId`, `loyaltyPoints` and `debug.ur.customer` |
| `MapToUR`   | In the `urCustomer` registration step, before a customer is created or updated. The customer is then read back, so `MapFromUR` runs too                                                              |
| Interceptor | On every SOAP call to Cegid UR, so anything slow in it slows the whole connector                                                                                                                     |

## Handlers

| Method            | Parameters                  | Returns                                     | Required | Sync or async                    |
| ----------------- | --------------------------- | ------------------------------------------- | -------- | -------------------------------- |
| `MapFromUR`       | `data`, `account`           | nothing                                     | Optional | Synchronous                      |
| `MapToUR`         | `account`, `data`           | nothing                                     | Optional | Synchronous                      |
| `OnBeforeRequest` | `url`, `headers`, `content` | a promise of `{ Url, Headers, Content }`    | Required | Asynchronous: declare it `async` |
| `OnAfterRequest`  | `soapAction`, `content`     | a promise of the response body, as a string | Required | Asynchronous: declare it `async` |

* **Mapper.** `data` is the Cegid UR customer (`CustomerType`). Its members are camelCase and come from the vendor contract: `data.person.firstName`, unlike the PascalCase members of Cegid Y2. The raw customer read from Cegid UR is visible under `debug.ur.customer`. In `MapToUR`, `data` is a new customer built from the account (id, `firstName`, `lastName`, `email`), not the record stored in Cegid UR. Either method may be omitted, so a script that customizes one direction registers only that one. Both change their arguments in place, and an `async` mapper is not awaited.
* **Interceptor.** `OnBeforeRequest` returns `{ Url, Headers, Content }` and the connector **replaces the URL and all headers** with what it returns: copy the received headers, add what is needed, and keep `SOAPAction`. Only the first value of each request header is passed in. `OnAfterRequest` receives every response body of the Cegid UR HTTP client, whatever its content, and returns it as a string. Both methods are required.

## Errors and edge cases

* **An interceptor method is missing**: the call fails with `method <Name> missing` on the first Cegid UR call.
* **The interceptor returns headers without `SOAPAction`**: the request is sent without it and the call then fails with an error, because the response step reads that header.
* **A script throws**: the error is not caught and fails the Cegid UR call, and with it the customer read or the registration step.
* **The secret is missing**: `getSecret` returns `null` and the header would carry no key. Check the value and fail with a clear message.

## Example

The interceptor reads the key from the secret store and adds it to every call. The header name `X-Api-Key` and the secret name are placeholders: use the ones Cegid UR expects for the brand's environment.

```js
import { getSecret } from 'twc/secrets';

async function onBeforeRequest(url, headers, content) {
  const key = await getSecret('CEGID-UR-KEY');
  if (!key) {
    throw new Error('Secret CEGID-UR-KEY is not set');
  }
  return { Url: url, Headers: { ...headers, 'X-Api-Key': key }, Content: content };
}

async function onAfterRequest(soapAction, content) {
  return content;
}

export default function (context) {
  context.register('extensions.cegid.ur.connectionInterceptor', {
    OnBeforeRequest: onBeforeRequest,
    OnAfterRequest: onAfterRequest
  });
}
```

The mapper below customizes one direction only:

```js
function mapFromUR(data, account) {
  if (data?.person?.firstName) {
    account['firstName'] = data.person.firstName;
  }
}

export default function (context) {
  context.register('extensions.cegid.ur.mapper', {
    MapFromUR: mapFromUR
  });
}
```

## Common pitfalls

* Y2 member names are used on a UR object: UR members are camelCase.
* The interceptor is registered with only one of its two methods.
* The Cegid UR rate limiter is disabled unless configured: set the limit in the configuration rather than in a script.


---

# 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/cegid-ur.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.
