> 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/connectors/pos/cegid/developer-reference/scripting-reference.md).

# Scripting reference

Reference for Cegid Retail Y2 and UR scripting extension points, supported helpers, secrets, and customer data structures.

Use this reference with [Customise the mapping](/connectors/pos/cegid/customer-data-and-loyalty/customise-the-mapping.md). It lists script extension points, available helpers, and the Cegid customer object structure.

### Extension points

| Registration name                           | Methods                                                                                                    | Purpose                                                                                                                                             |
| ------------------------------------------- | ---------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| `extensions.cegid.y2.mapper`                | <p><code>MapToY2(account, data)</code><br><code>MapFromY2(data, account)</code></p>                        | Customise the customer field mapping in both directions. Both methods are required.                                                                 |
| `extensions.cegid.y2.advisorRepository`     | <p><code>Filter(advisor)</code><br><code>Project(advisor)</code></p>                                       | Narrow and reshape the salesperson list Cegid returns. Both methods are required; supplying this endpoint replaces the default projection entirely. |
| `extensions.cegid.y2.connectionInterceptor` | <p><code>OnBeforeRequest(url, headers, content)</code><br><code>OnAfterRequest(action, content)</code></p> | Inspect or alter every call to Cegid. Used where a brand fronts Cegid with its own gateway, or for diagnostic capture.                              |
| `extensions.cegid.ur.mapper`                | <p><code>MapToUR(account, data)</code><br><code>MapFromUR(data, account)</code></p>                        | The Cegid UR equivalent. Unlike Y2, either method may be omitted.                                                                                   |
| `extensions.cegid.ur.connectionInterceptor` | As the Y2 interceptor                                                                                      | Commonly used to inject an authentication header from the secret store.                                                                             |

#### When each runs

The mapper runs once per customer write and once per read. A create or update performs both, because the record is read back after writing. The advisor repository runs once per salesperson on every advisor list request. The connection interceptor runs on **every** call to Cegid, so anything expensive in it is multiplied accordingly.

{% hint style="warning" %}
If no script registers an endpoint, the default behaviour applies and nothing fails. If a script registers the endpoint but omits a required method, the call fails when it is reached. If a script file contains a syntax error, **no** script endpoint loads for that tenant. And where two files register the same name, the last one loaded wins.
{% endhint %}

### Helpers available to scripts

The following are available as globals, without an import.

| Helper        | Signature                            | Purpose                                                                                                                                                                                                                                             |
| ------------- | ------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ensureLatin` | `ensureLatin(value, replacement?)`   | Folds look-alike Unicode — full-width forms, Cyrillic and Greek homoglyphs, accents — down to ASCII. Where a replacement character is given, any remaining non-ASCII character is replaced with it. Useful for systems that reject non-Latin input. |
| `fetch`       | `fetch(url, options?)`               | HTTP client, restricted to public addresses. Supports caching, throttling, and several authentication schemes.                                                                                                                                      |
| `console`     | `console.log / info / warn / error`  | Writes to the tenant logs. Never pass the account object.                                                                                                                                                                                           |
| `CryptoJS`    | `CryptoJS.HmacSHA256(secret, value)` | Signing, for integrations requiring it.                                                                                                                                                                                                             |
| `sleep`       | `sleep(milliseconds)`                | Delays execution.                                                                                                                                                                                                                                   |
| `toDateTime`  | `toDateTime(value)`                  | Parses a value into a date, normalised to UTC.                                                                                                                                                                                                      |

Secrets are read through an import rather than a global, so that credentials never appear in the script itself.

```javascript
import { getSecret } from 'neo/secrets';

async function onBeforeRequest(url, headers, content) {
  headers["X-API-KEY"] = await getSecret('PARTNER-API-KEY');
  return { Url: url, Headers: headers, Content: content };
}
```

### The Cegid customer object

The object a mapper receives mirrors the Cegid customer structure. The fields below are those a mapping commonly touches.

#### Identity and classification

`FirstName`, `LastName`, `AlternateFirstName`, `AlternateLastName`, `ShortName`, `TitleId`, `Sex`, `NationalityId`, `LanguageId`, `CurrencyId`, `IsCompany`, `CompanyIdNumber`, `CompanyTitleId`, `FiscalId`, `ItalianFiscalId`, `PassportNumber`, `Barcode`, `Notepad`, `LongDescription`, `OriginCode`, `PriceListCode`, `RiskLevel`, `SalesPersonId`, `SalesPerson2Id`, `SalesPerson3Id`, `UsualStoreId`, `DirectMail`, `VATSystem`.

#### Nested blocks

| Block           | Properties                                                                                                               |
| --------------- | ------------------------------------------------------------------------------------------------------------------------ |
| `EmailData`     | `Email`, `AlternativeEmail`, `EmailingAccepted`, `SendReceiptByMail`                                                     |
| `PhoneData`     | `CellularPhoneNumber`, `HomePhoneNumber`, `OfficePhoneNumber`, `AlternativePhoneNumber`                                  |
| `AddressData`   | `AddressLine1`, `AddressLine2`, `AddressLine3`, `City`, `ZipCode`, `RegionId`, `CountryId`, `CountryIdType`, `BrandName` |
| `BirthDateData` | `BirthDateDay`, `BirthDateMonth`, `BirthDateYear`                                                                        |

{% hint style="warning" %}
Nested blocks may be absent. A customer with no address has no address block at all, and writing into it without creating it first fails the entire save.
{% endhint %}

#### Consent classification

The consent fields — `OptinEmail`, `OptinMobile`, `OptinPostal`, `OptinHomePhone`, `OptinOfficePhone`, `OptinAlternativeEmail` — take one of four values rather than a boolean.

| Value              | Meaning                                         |
| ------------------ | ----------------------------------------------- |
| `0` — ask customer | Not yet established.                            |
| `1` — brand only   | May be contacted by the brand.                  |
| `2` — for partners | May be contacted by the brand and its partners. |
| `3` — do not use   | Must not be contacted on this channel.          |

The default mapping writes brand-only for consent and do-not-use for refusal. Which value a brand considers to represent consent is a business decision to confirm rather than assume.

#### Free field containers

`UserDefinedData` offers ten slots as properties numbered from zero. `UserDefinedTexts`, `UserDefinedBooleans`, `UserDefinedDates`, and `UserDefinedValues` are arrays offering **three** slots each, identified from zero. `UserFields` hold typed entries against identifiers defined in the brand's Cegid configuration. Worked examples are in [Customise the mapping](/connectors/pos/cegid/customer-data-and-loyalty/customise-the-mapping.md).

A `UserFields` entry carries a value type identifying which of its value properties applies.

| Value type         | Property to set    |
| ------------------ | ------------------ |
| `0` — boolean      | `BooleanValue`     |
| `1` — text         | `TextValue`        |
| `2` — date         | `DateValue`        |
| `3` — list element | `ListElementValue` |
| `4` — number       | `NumberValue`      |

#### Country identifiers

`AddressData.CountryIdType` states how `CountryId` should be read: an internal Cegid identifier, ISO-2, ISO-3, or ISO-3 numeric. The default mapping writes ISO-2 and converts back to ISO-2 on reading, whichever form Cegid returns.

### FAQ

<details>

<summary><strong>Can a script call an external service?</strong></summary>

Yes, using the `fetch` helper, which is restricted to public addresses and supports caching and throttling. Bear in mind that the mapper runs on every customer read, so an external call in it multiplies accordingly.

</details>

<details>

<summary><strong>Where should an API key used by a script be stored?</strong></summary>

In the secret store, read with `getSecret`. Keys should not appear in script source, which is visible to anyone with access to the tenant configuration.

</details>


---

# 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/connectors/pos/cegid/developer-reference/scripting-reference.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.