Customise the mapping

Customise Cegid Retail Y2 field mapping for wallet installation, languages, consents, preferences, and brand-specific customer data.

The default mapping covers identity and contact fields. A script maps other Cegid data, including preferences, language, wallet installation state, and fiscal identifiers. This page defines the script contract, practical recipes, and safe mapping patterns.

Nearly every brand running this connector deploys a mapping script. It should be treated as part of the initial implementation rather than as an optional extra.

The contract

A mapping script registers two functions. MapToY2 receives the wallet account and the Cegid customer structure, and runs immediately before the record is written. MapFromY2 receives the Cegid record and the wallet account, and runs immediately after a record is read. Both run after the default mapping, so either can override it.

Both functions are required. Registering only one causes the other to fail when it is called.

// server/scripts/y2.mapping.js

const mapToY2 = function (account, data) { /* wallet -> Cegid */ };
const mapFromY2 = function (data, account) { /* Cegid -> wallet */ };

export default function (context) {
  context.register('extensions.cegid.y2.mapper', {
    MapToY2: mapToY2,
    MapFromY2: mapFromY2
  });
}

The script is edited in the Mapping tab of the Cegid configuration page. The shape of the Cegid customer object it receives is documented in the Scripting reference.

All scripts in a tenant are loaded together. A syntax error in any one file prevents every script endpoint from loading, not only the file containing the error, so a mistake in an unrelated script disables the Cegid mapping too.

Writing against real data

While a mapping is being written, the raw Cegid response is available on the account under debug.y2.customer, with equivalents for loyalty, sales documents, and cash operations. These make it possible to see exactly what Cegid returned for a given customer. They are a development aid available to the script, not fields that can be used in a pass template.

Cegid's extensible fields

Cegid provides several containers for brand-specific data, and choosing the right one is the first decision in any mapping.

Container	Shape	Slots
UserDefinedData	An object with properties UserDefinedTable0Value … UserDefinedTable9Value	10
UserDefinedTexts	An array of { Id, Value }, value is text	3
UserDefinedBooleans	An array of { Id, Value }, value is true or false	3
UserDefinedDates	An array of { Id, Value }, value is a date	3
UserDefinedValues	An array of { Id, Value }, value is a number	3
UserFields	An array of typed entries with a numeric identifier	Defined per Cegid configuration

Identifiers start at zero; Cegid labels start at one. In every array container, Id: 0 is the field a Cegid user sees labelled as the first one, Id: 1 the second, and Id: 2 the third. The same offset applies to UserDefinedTable0Value, which is the first free table. This is the single most common cause of a value arriving in the wrong Cegid field, and it is worth a comment on every constant.

Recipes

Wallet installation state

Recording whether a customer installed the pass, and on which platform, is the most frequently implemented customisation. It is what lets a brand build campaign selections in Cegid around wallet adoption.

The pattern writes a code into a free table. Two details determine whether the resulting data is usable. The platform states must be compared to the literal value rather than tested for truthiness, because the state of a removed pass is a non-empty string and would otherwise read as installed. And the negative case must be written: a mapping that records installation but never records its absence produces a segment that only ever grows.

// Free table 3 holds wallet installation state.
// Confirm the slot with the brand: the same ordinal points at a
// different business field in every Cegid database.
const INSTALL_SLOT = "UserDefinedTable2Value";

const NOT_INSTALLED = "000";
const APPLE_ONLY    = "001";
const GOOGLE_ONLY   = "002";
const BOTH          = "003";

function installCode(account) {
  // Compare to the literal state. "Uninstalled" is a truthy string,
  // so a truthiness test reports a removed pass as installed.
  const apple  = account["neo.pass.Apple.state"]  === "Installed";
  const google = account["neo.pass.Google.state"] === "Installed";
  if (apple && google) return BOTH;
  if (apple)           return APPLE_ONLY;
  if (google)          return GOOGLE_ONLY;
  return NOT_INSTALLED;   // explicit, not empty
}

const mapToY2 = function (account, data) {
  data.UserDefinedData = { ...data.UserDefinedData, [INSTALL_SLOT]: installCode(account) };
};

const mapFromY2 = function (data, account) {
  account.installState = data.UserDefinedData?.[INSTALL_SLOT] || NOT_INSTALLED;
};

An explicit "000" is preferable to an empty value, because a blank cannot be distinguished from a field that was never written, which makes it impossible to build a selection of customers who removed the pass.

This recipe depends on the connector writing back to Cegid when a pass is installed or removed, which is the Update customer on pass installation change setting described in Advanced configuration.

Language

Cegid carries a proprietary language identifier, and there is no common code table across Cegid databases: the codes are defined per database. A language table taken from another implementation is a guess, and the correct codes have to come from the brand's own Cegid configuration.

The reverse table should be derived from the forward one rather than written out separately. Independently written tables drift, and the resulting defect is subtle: a customer saved in one language reads back in another.

// Cegid-side codes for THIS Cegid database.
const LANGUAGES = { fr: "FRA", en: "ANG", es: "ESP", de: "ALL" };
const DEFAULT_LANGUAGE = "ANG";

// Derived, so the two directions cannot drift apart.
const LANGUAGES_REVERSE = Object.fromEntries(
  Object.entries(LANGUAGES).map(([locale, code]) => [code, locale])
);

const mapToY2 = function (account, data) {
  const locale = (account.neo?.lng || "").toLowerCase().split("-")[0];
  data.LanguageId = LANGUAGES[locale] || DEFAULT_LANGUAGE;
};

const mapFromY2 = function (data, account) {
  const locale = LANGUAGES_REVERSE[data.LanguageId];
  if (locale) account.language = locale;  // unknown: leave untouched
};

Normalising the locale before lookup, by lowercasing it and dropping the regional part, prevents regional variants from silently missing. An unknown language should fall back to a documented default rather than to an empty value.

Consents in free booleans

Cegid offers two places to record marketing consent. The Optin fields are a four-value classification rather than a yes-or-no, listed in the Scripting reference. Which of the middle values counts as consent is a business decision that has to be agreed with the brand; it is not self-evident.

Free booleans are the more common choice, and are unambiguous. The pattern below shows the general form for writing into any array container: filter out the existing entry, then append.

const CONSENT_EMAIL_ID = 0;   // free boolean 1

function upsert(list, id, entry) {
  return [...(list || []).filter((e) => e?.Id != id), { Id: id, ...entry }];
}

const mapToY2 = function (account, data) {
  // Skip only when the form collected no answer at all.
  // When it did, write false as readily as true.
  if (typeof account.consents_email === "boolean") {
    data.UserDefinedBooleans = upsert(data.UserDefinedBooleans, CONSENT_EMAIL_ID, {
      Value: account.consents_email
    });
  }
};

const mapFromY2 = function (data, account) {
  // find, not filter: filter returns an array, whose .Value is undefined
  const entry = (data.UserDefinedBooleans || []).find((e) => e?.Id == CONSENT_EMAIL_ID);
  if (entry) account.consents_email = !!entry.Value;
};

Free texts

Free texts follow the same array pattern, and the same offset applies: Id: 2 is the field labelled as the third.

const LOYALTY_NOTE_ID = 2;   // free text 3

const mapToY2 = function (account, data) {
  if (account.note) {
    data.UserDefinedTexts = upsert(data.UserDefinedTexts, LOYALTY_NOTE_ID, { Value: account.note });
  }
};

const mapFromY2 = function (data, account) {
  const v = (data.UserDefinedTexts || []).find((e) => e?.Id == LOYALTY_NOTE_ID)?.Value;
  if (v) account.note = v;
};

Preference lists

UserFields hold typed entries against identifiers defined in the brand's Cegid configuration. A list-element field carries a value from a Cegid-defined list, and the value type identifies which kind of entry it is.

const PREFERENCE_IDS = [1, 2, 3];   // agreed with the brand
const LIST_ELEMENT = 3;             // UserField value type

const mapToY2 = function (account, data) {
  for (const id of PREFERENCE_IDS) {
    const answered = account["preference" + id];
    if (answered === undefined) continue;
    // Write NO as well as YES, or a withdrawn preference never reaches Cegid.
    data.UserFields = upsert(data.UserFields, id, {
      ValueType: LIST_ELEMENT,
      ListElementValue: answered ? "YES" : "NO"
    });
  }
};

Standard fields the default mapping leaves alone

Several standard Cegid fields are not part of the default mapping but are commonly needed. The address block may be absent on a new record, so it has to be created before anything is written into it.

const mapToY2 = function (account, data) {
  // AddressData can be absent. Writing into it unguarded throws,
  // and the whole save fails.
  if (!data.AddressData) data.AddressData = {};
  data.AddressData.RegionId     = account.state || "";
  data.AddressData.AddressLine3 = account.address3;

  data.PassportNumber = account.passport;
  if (account.fiscalCode) data.FiscalId = account.fiscalCode.toUpperCase();
  if (account.comment)    data.Notepad  = account.comment;

  // Alternate names carry a second script, for example a Latin form
  // alongside a local one.
  data.AlternateFirstName = account.firstNameLatin;
  data.AlternateLastName  = account.lastNameLatin;
};

Practices worth following

Replace entries, never append to them

The array containers round-trip whatever is already on the record. Appending without first removing the existing entry adds a duplicate on every save, and which duplicate Cegid honours is arbitrary.

// Wrong: grows on every save.
data.UserFields = [...(data.UserFields || []), { Id: id, /* ... */ }];

// Right: remove, then add.
data.UserFields = [...(data.UserFields || []).filter((e) => e?.Id != id), { Id: id, /* ... */ }];

The opposite error is as damaging: assigning a fresh array replaces the whole container, discarding free fields the brand maintains by hand in Cegid.

Keep the two directions symmetric

Any table used in MapToY2 must be used in MapFromY2, and the reverse direction should be derived rather than retyped. Two independently written tables eventually disagree, and the symptom, a value that changes into a different value across a save, is hard to attribute.

The same applies to codes: a read path that recognises a code the write path never produces is dead, usually because the script was copied from another implementation.

Write the negative case

A field that the wallet can set must also be one the wallet can clear. Mappings that record only the positive case produce data that can never be corrected: a preference that cannot be withdrawn, an adoption segment that only grows.

Guard reads and writes

Nested objects may be absent. Writing into data.AddressData without creating it first fails the entire save, and reading data.UserDefinedData.X without the optional-chaining form fails on a customer who has never had a free field set.

Never log the account

The account object carries names, email addresses, telephone numbers, and dates of birth. Logging it places personal data into platform logs. Where a trace is genuinely needed, a single derived value should be logged instead.

Anti-patterns

Anti-pattern	What is observed
Appending to an array without filtering	Duplicate entries accumulate on each save; the effective value becomes unpredictable.
Assigning a whole new array	Free fields maintained by hand in Cegid disappear the first time the wallet saves.
Using filter where find was meant	The value reads back as undefined permanently. No error is raised; the form simply never pre-fills.
Separate forward and reverse tables	Two values swap places; a record saved as one reads back as the other.
Testing a state string for truthiness	A removed pass counts as installed; platform attribution freezes at its first value.
Writing only the positive value	The segment grows and never shrinks; customers cannot be removed from it.
A guard that makes the negative branch unreachable	Opt-ins reach Cegid; opt-outs never do.
Unguarded write into a nested object	The mapper throws for any customer lacking that block, and the whole save fails.
Logging the account object	Personal data in platform logs.
A commented-out copy of the mapper left in place	The next maintainer edits the dead copy.

Starter script

The script below combines the recipes above and can be used as a starting point.

// server/scripts/y2.mapping.js
//
// Conventions used here:
//  - Free-field identifiers are zero-based; the Cegid label is one higher.
//    Every constant carries a comment naming the Cegid field.
//  - Array fields are written filter-then-append, never appended to.
//  - Mapping tables are declared once and reversed programmatically.
//  - Every field that can be set can also be unset.

// ------------------------------------------------------------ constants

const INSTALL_SLOT = "UserDefinedTable2Value";  // free table 3
const NOT_INSTALLED = "000", APPLE_ONLY = "001",
      GOOGLE_ONLY = "002", BOTH = "003";

const CONSENT_EMAIL_ID = 0;   // free boolean 1
const PREFERENCE_IDS   = [1, 2, 3];
const LIST_ELEMENT     = 3;

const LANGUAGES = { fr: "FRA", en: "ANG", es: "ESP" };
const DEFAULT_LANGUAGE = "ANG";
const LANGUAGES_REVERSE = Object.fromEntries(
  Object.entries(LANGUAGES).map(([l, c]) => [c, l])
);

// -------------------------------------------------------------- helpers

function upsert(list, id, entry) {
  return [...(list || []).filter((e) => e?.Id != id), { Id: id, ...entry }];
}

function installCode(account) {
  const apple  = account["neo.pass.Apple.state"]  === "Installed";
  const google = account["neo.pass.Google.state"] === "Installed";
  if (apple && google) return BOTH;
  if (apple)           return APPLE_ONLY;
  if (google)          return GOOGLE_ONLY;
  return NOT_INSTALLED;
}

// -------------------------------------------------------- wallet -> Cegid

const mapToY2 = function (account, data) {

  const locale = (account.neo?.lng || "").toLowerCase().split("-")[0];
  data.LanguageId = LANGUAGES[locale] || DEFAULT_LANGUAGE;

  if (!data.AddressData) data.AddressData = {};
  data.AddressData.RegionId = account.state || "";

  data.UserDefinedData = { ...data.UserDefinedData, [INSTALL_SLOT]: installCode(account) };

  if (typeof account.consents_email === "boolean") {
    data.UserDefinedBooleans =
      upsert(data.UserDefinedBooleans, CONSENT_EMAIL_ID, { Value: account.consents_email });
  }

  for (const id of PREFERENCE_IDS) {
    const answered = account["preference" + id];
    if (answered === undefined) continue;
    data.UserFields = upsert(data.UserFields, id, {
      ValueType: LIST_ELEMENT,
      ListElementValue: answered ? "YES" : "NO"
    });
  }
};

// -------------------------------------------------------- Cegid -> wallet

const mapFromY2 = function (data, account) {

  const locale = LANGUAGES_REVERSE[data.LanguageId];
  if (locale) account.language = locale;

  account.state = data.AddressData?.RegionId;
  account.installState = data.UserDefinedData?.[INSTALL_SLOT] || NOT_INSTALLED;

  const consent = (data.UserDefinedBooleans || []).find((e) => e?.Id == CONSENT_EMAIL_ID);
  if (consent) account.consents_email = !!consent.Value;

  for (const id of PREFERENCE_IDS) {
    const f = (data.UserFields || []).find((e) => e?.Id == id);
    if (f) account["preference" + id] = f.ListElementValue === "YES";
  }
};

// --------------------------------------------------------- registration

export default function (context) {
  context.register('extensions.cegid.y2.mapper', { MapToY2: mapToY2, MapFromY2: mapFromY2 });
}

FAQ

A value is being written into the wrong Cegid field. Why?

Almost always the zero-based identifier. The field a Cegid user calls the third free text is Id: 2 in a script. Confirming the intended field with the brand by its Cegid label, and commenting the constant accordingly, prevents it.

A field saves but never reads back. Why?

The most common cause is using filter where find was intended. filter returns an array, and reading a value from an array yields nothing, silently and with no error.

Can a mapping script override the default mapping?

Yes. The script runs after the default mapping on both paths, so any field it sets takes precedence.

Can a language table be copied from another implementation?

No. Cegid language identifiers are defined per database. The codes have to come from the brand's own Cegid configuration.

No customisation appears to take effect at all. What should be checked?

A syntax error in any script file, not necessarily the mapping file, prevents every script from loading for that tenant. Reviewing the other scripts is the first step.