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. It lists script extension points, available helpers, and the Cegid customer object structure.

Extension points

Registration name	Methods	Purpose
extensions.cegid.y2.mapper	MapToY2(account, data) MapFromY2(data, account)	Customise the customer field mapping in both directions. Both methods are required.
extensions.cegid.y2.advisorRepository	Filter(advisor) Project(advisor)	Narrow and reshape the salesperson list Cegid returns. Both methods are required; supplying this endpoint replaces the default projection entirely.
extensions.cegid.y2.connectionInterceptor	OnBeforeRequest(url, headers, content) OnAfterRequest(action, content)	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	MapToUR(account, data) MapFromUR(data, account)	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.

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.

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.

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

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.

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.

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

Can a script call an external service?

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.

Where should an API key used by a script be stored?

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.