Référence de script

Référence pour les points d’extension de script Cegid Retail Y2 et UR, les helpers pris en charge, les secrets et les structures de données client.

Utilisez cette référence avec Personnaliser le mappage. Elle répertorie les points d'extension du script, les utilitaires disponibles et la structure de l'objet client Cegid.

Points d'extension

Nom d'enregistrement	Méthodes	Objectif
extensions.cegid.y2.mapper	MapToY2(account, data) MapFromY2(data, account)	Personnalisez le mappage des champs client dans les deux sens. Les deux méthodes sont requises.
extensions.cegid.y2.advisorRepository	Filter(advisor) Project(advisor)	Réduisez et remodelez la liste des commerciaux renvoyée par Cegid. Les deux méthodes sont requises ; fournir ce point de terminaison remplace entièrement la projection par défaut.
extensions.cegid.y2.connectionInterceptor	OnBeforeRequest(url, headers, content) OnAfterRequest(action, content)	Inspectez ou modifiez chaque appel à Cegid. Utilisé lorsqu'une marque front-end Cegid avec sa propre passerelle, ou pour une capture de diagnostic.
extensions.cegid.ur.mapper	MapToUR(account, data) MapFromUR(data, account)	L'équivalent UR de Cegid. Contrairement à Y2, l'une ou l'autre méthode peut être omise.
extensions.cegid.ur.connectionInterceptor	Comme l'intercepteur Y2	Couramment utilisé pour injecter un en-tête d'authentification depuis le coffre de secrets.

Quand chacun s'exécute

Le mappeur s'exécute une fois par écriture client et une fois par lecture. Une création ou une mise à jour effectue les deux, car l'enregistrement est relu après l'écriture. Le dépôt des conseillers s'exécute une fois par commercial à chaque demande de liste des conseillers. L'intercepteur de connexion s'exécute sur chaque chaque appel à Cegid, donc tout ce qu'il y a de coûteux est multiplié en conséquence.

Si aucun script n'enregistre un point de terminaison, le comportement par défaut s'applique et rien n'échoue. Si un script enregistre le point de terminaison mais omet une méthode requise, l'appel échoue lorsqu'il est atteint. Si un fichier de script contient une erreur de syntaxe, aucune le point de terminaison du script se charge pour ce locataire. Et lorsque deux fichiers enregistrent le même nom, le dernier chargé l'emporte.

Utilitaires disponibles pour les scripts

Les éléments suivants sont disponibles en tant que variables globales, sans import.

Utilitaire	Signature	Objectif
ensureLatin	ensureLatin(value, replacement?)	Aplanit les caractères Unicode ressemblants — formes pleine largeur, homoglyphes cyrilliques et grecs, accents — vers l'ASCII. Lorsqu'un caractère de remplacement est fourni, tout caractère non ASCII restant est remplacé par celui-ci. Utile pour les systèmes qui refusent les entrées non latines.
fetch	fetch(url, options?)	Client HTTP, limité aux adresses publiques. Prend en charge la mise en cache, la limitation de débit et plusieurs schémas d'authentification.
console	console.log / info / warn / error	Écrit dans les journaux du locataire. Ne transmettez jamais l'objet account.
CryptoJS	CryptoJS.HmacSHA256(secret, value)	Signature, pour les intégrations qui en ont besoin.
sleep	sleep(milliseconds)	Retarde l'exécution.
toDateTime	toDateTime(value)	Analyse une valeur en une date, normalisée en UTC.

Les secrets sont lus via un import plutôt que via une variable globale, afin que les identifiants n'apparaissent jamais dans le script lui-même.

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 };
}

L'objet client Cegid

L'objet reçu par un mappeur reflète la structure du client Cegid. Les champs ci-dessous sont ceux qu'un mappage manipule couramment.

Identité et 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.

Blocs imbriqués

Bloc	Propriétés
EmailData	Email, AlternativeEmail, EmailingAccepted, SendReceiptByMail
PhoneData	CellularPhoneNumber, HomePhoneNumber, OfficePhoneNumber, AlternativePhoneNumber
AddressData	AddressLine1, AddressLine2, AddressLine3, City, ZipCode, RegionId, CountryId, CountryIdType, BrandName
BirthDateData	BirthDateDay, BirthDateMonth, BirthDateYear

Les blocs imbriqués peuvent être absents. Un client sans adresse n'a aucun bloc d'adresse, et y écrire sans l'avoir créé au préalable fait échouer l'enregistrement complet.

Classification du consentement

Les champs de consentement — OptinEmail, OptinMobile, OptinPostal, OptinHomePhone, OptinOfficePhone, OptinAlternativeEmail — prennent l'une des quatre valeurs plutôt qu'un booléen.

Valeur	Signification
0 — demander au client	Pas encore établi.
1 — marque uniquement	Peut être contacté par la marque.
2 — pour les partenaires	Peut être contacté par la marque et ses partenaires.
3 — ne pas utiliser	Ne doit pas être contacté via ce canal.

Le mappage par défaut écrit « marque uniquement » pour le consentement et « ne pas utiliser » pour le refus. La valeur qu'une marque considère comme représentant le consentement est une décision métier à confirmer plutôt qu'à supposer.

Conteneurs de champs libres

UserDefinedData offre dix emplacements sous forme de propriétés numérotées à partir de zéro. UserDefinedTexts, UserDefinedBooleans, Dates définies par l’utilisateur, et Valeurs définies par l’utilisateur sont des tableaux offrant trois emplacements chacun, identifiés à partir de zéro. Champs définis par l’utilisateur contiennent des entrées typées associées à des identifiants définis dans la configuration Cegid de la marque. Des exemples détaillés se trouvent dans Personnaliser le mappage.

A Champs définis par l’utilisateur Une entrée porte un type de valeur indiquant quelle propriété de valeur s'applique.

Type de valeur	Propriété à définir
0 — boolean	BooleanValue
1 — texte	TextValue
2 — date	DateValue
3 — élément de liste	ListElementValue
4 — nombre	NumberValue

Identifiants de pays

AddressData.CountryIdType indique comment CountryId doit être lu : un identifiant interne Cegid, ISO-2, ISO-3 ou ISO-3 numérique. Le mappage par défaut écrit en ISO-2 et reconvertit en ISO-2 à la lecture, quelle que soit la forme renvoyée par Cegid.

FAQ

Un script peut-il appeler un service externe ?

Oui, en utilisant le fetch utilitaire, qui est limité aux adresses publiques et prend en charge la mise en cache et la limitation de débit. Gardez à l'esprit que le mappeur s'exécute à chaque lecture de client, donc un appel externe en son sein se multiplie en conséquence.

Où doit être stockée une clé API utilisée par un script ?

Dans le coffre de secrets, lue avec getSecret. Les clés ne doivent pas apparaître dans le code source du script, qui est visible par toute personne ayant accès à la configuration du locataire.