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

# Secutix scripts

Reference of the four Secutix scripts, contact mapper, contact pass updater, movement mapper and ticket pass type finder: signatures and examples.

Four scripts adjust the Secutix connector. The contact mapper maps the wallet account to a Secutix contact and back. The contact pass updater writes the wallet installation status into the Secutix contact. The movement mapper adds values from a ticket to the pass data. The ticket pass type finder chooses the pass type of a ticket. This page is the reference for `extensions.secutix.contact.mapper`, `extensions.secutix.contact.passUpdater`, `extensions.secutix.movement.mapper` and `extensions.secutix.ticket.passTypeFinder`. The connector is described on the [Secutix connector pages](https://docs.thewalletcrew.io/connectors/ticketing/secutix/template-selection.md); the rules shared by every connector script are in [Connector scripts](https://docs.thewalletcrew.io/developers-guides/scripting/extensions.md). A script that must call another Secutix service uses the [twc/secutix module](https://docs.thewalletcrew.io/developers-guides/scripting/modules/secutix.md).

<details>

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

* A club sends the email consent of the wallet account to a Secutix contact criterion.
* A club records in the Secutix contact whether its member card is installed on Apple Wallet or Google Wallet.
* A venue sends tickets of one hall to a dedicated pass type.
* An organizer adds the stage visibility of a movement to the data a ticket template reads.

</details>

## Registration

| Key                                        | Slot file                          | Methods (required in **bold**)        |
| ------------------------------------------ | ---------------------------------- | ------------------------------------- |
| `extensions.secutix.contact.mapper`        | `secutix.contact.mapper.js`        | `MapToSecutix`, `MapToNeostore`       |
| `extensions.secutix.contact.passUpdater`   | `secutix.contact.passUpdater.js`   | **`OnPassInstallationStatusChanged`** |
| `extensions.secutix.movement.mapper`       | `secutix.movement.mapper.js`       | **`MapFromSecutix`**                  |
| `extensions.secutix.ticket.passTypeFinder` | `secutix.ticket.passTypeFinder.js` | **`GetPassType`**                     |

The slots are in the **Advanced** tab of the Secutix configuration page, and are read and written with `GET` and `PUT /api/{tenantId}/admin/extensions/secutix/scripts`; the [API reference](https://docs.thewalletcrew.io/api-reference/) describes them. When no script is registered for a key, the default behavior applies.

## When it runs

| Script                            | Runs                                                                                                                                                                                                      |
| --------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `contact.mapper`: `MapToSecutix`  | In the registration flow step, before the contact is saved in Secutix, after the default mapping                                                                                                          |
| `contact.mapper`: `MapToNeostore` | After Secutix answers, when the contact is read, to map it back to the account                                                                                                                            |
| `contact.passUpdater`             | When the installation status of a member card changes, only for passes whose identifiers carry the Secutix contact number                                                                                 |
| `movement.mapper`                 | After the default `ticket.*` mapping of a movement                                                                                                                                                        |
| `ticket.passTypeFinder`           | When the pass type of a ticket is chosen. The order is: this hook, then the `WALLET` comfort variable of the operation (then of the product), then the product family subtype, then the default pass type |

The default contact mapping writes `email` to `Email`, `lastName` to `IndividualLastname`, `firstName` to `IndividualFirstname`, `phoneNumber` to `PhoneNumber1` and `neo.lng` to `IndividualPreferredLanguage` (left empty when the account has no `neo.lng`; `MapToSecutix` can set it), and sets `IndividualTitle` to `UNDEFINED`. The prefix `neostore` is the platform's former name and is kept in technical identifiers: `MapToNeostore` means "map back to the account" and its name cannot be changed.

## Handlers

| Key                     | Method                            | Parameters                                                         | Returns                                     | Required | Sync or async                    |
| ----------------------- | --------------------------------- | ------------------------------------------------------------------ | ------------------------------------------- | -------- | -------------------------------- |
| `contact.mapper`        | `MapToSecutix`                    | `account`, `request`                                               | nothing                                     | Optional | Synchronous                      |
| `contact.mapper`        | `MapToNeostore`                   | `response`, `account`                                              | nothing                                     | Optional | Synchronous                      |
| `contact.passUpdater`   | `OnPassInstallationStatusChanged` | `request`, `isInstalled`, `device`                                 | nothing                                     | Required | Synchronous                      |
| `movement.mapper`       | `MapFromSecutix`                  | `data` (`{ Movement, Operation, Product?, Timeslot? }`), `account` | nothing                                     | Required | Synchronous                      |
| `ticket.passTypeFinder` | `GetPassType`                     | `movementData`, `operationData?`, `product?`                       | a promise of a pass type name, or of `null` | Required | Asynchronous: declare it `async` |

* **Different signatures.** `GetPassType` takes three positional arguments. `MapFromSecutix` takes **one** object with the members `Movement`, `Operation`, `Product` and `Timeslot`. `Product` and `Timeslot` can be absent. In `GetPassType`, `operationData` can also be absent, and `product` is fetched only when the operation carries a product id.
* **Install hook.** `request` is a new Secutix `SaveIndividualContactRequest`, saved right after the hook: it carries the `ContactNumber`, an empty `IndividualContactData` and no criterion. `device` is `0` for Apple and `2` for Google. The hook changes `request` in place and is synchronous: an `async` hook that awaits loses its changes, because the request is saved without waiting. Without the script, the contact is not written.
* **Pass type.** The returned name must be a pass type of the tenant. A name that is not configured, even one returned by the hook, is logged as an error and replaced by the subtype or the default mapping, skipping `WALLET`. The `WALLET` comfort variable is compared without regard to case, and the product's own `WALLET` variable is tried when the operation has none.
* **Product family subtypes.** When nothing else gives a pass type, the connector uses the default pass template configured for the product family subtype of the operation, in the **Default** section of the Secutix settings: `MEMBERSHIP` → **Membership**, `SEASONTICKET` → **Season ticket**, `SIMPLE_TICKET` → **Event**, `SPORTING_EVENT` → **Match**, `VISIT_PASS` → **Visit pass**, `OPEN_PASS` → **Open pass**, `OPEN` → **Open product**, `VOUCHER` → **Voucher**, `DONATION` → **Donation**, `SERVICE` → **Service**. When that field is empty, or for any other subtype, the **Default** pass template is used.

{% hint style="warning" %}
The default mapping sets no criterion: `request.ExternalContactCriterionData` is empty when `MapToSecutix` and `OnPassInstallationStatusChanged` start. Assigning `request.ExternalContactCriterionData = [...]` replaces what a script set earlier on the same request, so add to the list instead of assigning, as in the examples below.
{% endhint %}

## Errors and edge cases

* **A required method is missing**: the call fails with `method <Name> missing` when the connector reaches it.
* **`operationData` or `product` is absent**: `operationData.Site` throws. Guard it with `?.`.
* **`GetPassType` returns an unknown name**: logged as an error, and the default resolution applies.
* **A script throws**: the error reaches the operation that called it.
* **A synchronous method is declared `async`**: it is not awaited, so changes made after an `await` are lost.

## Example

The contact mapper writes the email consent as a criterion without removing the criteria already on the request, and reads it back. The criterion code `OPT_CO` comes from the connector page: use the codes of the brand's Secutix configuration.

```js
function mapToSecutix(account, request) {
  const criteria = request.ExternalContactCriterionData || [];
  criteria.push({ CriterionIdCode: 'OPT_CO', Values: [account['consents_email'] ? 'true' : 'false'] });
  request.ExternalContactCriterionData = criteria;
}

function mapToNeostore(response, account) {
  const criteria = response.ContactCriteria || [];
  const optIn = criteria.find((c) => c.CriterionIdCode === 'OPT_CO' && c.Values != null && c.Values[0] === 'true');
  account['consents_email'] = !!optIn;
}

export default function (context) {
  context.register('extensions.secutix.contact.mapper', {
    MapToSecutix: mapToSecutix,
    MapToNeostore: mapToNeostore
  });
}
```

The pass type finder routes two halls to dedicated pass types. It guards `operationData`, which can be absent:

```js
async function getPassType(movementData, operationData, product) {
  const site = operationData?.Site;
  if (site === 'Hall A') {
    return 'HALLA';
  }
  if (site === 'Hall B') {
    return 'HALLB';
  }
  return null;
}

export default function (context) {
  context.register('extensions.secutix.ticket.passTypeFinder', {
    GetPassType: getPassType
  });
}
```

The movement mapper exposes one value to the templates:

```js
function mapFromSecutix(data, account) {
  const stageVisibility = data?.Movement?.StageVisibility;
  if (stageVisibility != null) {
    account['ticket.stageVisibility'] = stageVisibility;
  }
}

export default function (context) {
  context.register('extensions.secutix.movement.mapper', {
    MapFromSecutix: mapFromSecutix
  });
}
```

The install hook records the status in a criterion per wallet. The values `Installé` and `Désinstallé` are specific to the project of the connector page: use the values the Secutix criterion accepts.

```js
function onPassInstallationStatusChanged(request, isInstalled, device) {
  const criteria = request.ExternalContactCriterionData || [];
  criteria.push({
    CriterionIdCode: device === 0 ? 'W_APPLE' : 'W_GOOGLE',
    Values: [isInstalled ? 'Installé' : 'Désinstallé']
  });
  request.ExternalContactCriterionData = criteria;
}

export default function (context) {
  context.register('extensions.secutix.contact.passUpdater', {
    OnPassInstallationStatusChanged: onPassInstallationStatusChanged
  });
}
```

`ExternalContactCriterionData` is a .NET list: it is read by index, has a `length` and accepts `push`, but `Array.isArray` returns `false` for it.

## Common pitfalls

* `ExternalContactCriterionData` is assigned in two hooks of the same project: the second assignment replaces the first.
* `operationData.Site` is read without a guard on an operation that has no site.
* `device` is compared with a string: it is `0` or `2`.
* The slot's registration lines are still commented out.


---

# 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/secutix.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.
