Règles de nommage

Les règles de nommage permettent d'éviter les conflits entre les extensions de développement de partenaires différents. Elles empêchent la superposition des tâches des autres partenaires dans la couche verticale.

Les plages de nommage sont, depuis la première version du logiciel, les suivantes :

• couche standard : A-V(A étant le module superviseur),
• couche verticale : X-Y,
• couche spécifique : Z.

Les éléments commençant par un W correspondent aux éléments générés automatiquement, tels que les transactions.

Des plages de menus locaux et des tables diverses étaient consacrées à la couche verticale.

Lorsqu'un partenaire est le seul à utiliser un dossier client, ces règles sont facilement applicables.

Toutefois, notre clientèle exige aujourd'hui un espace commercial qui lui permette de sélectionner des extensions de différents partenaires et de les installer rapidement dans son environnement.

Sans règles, il est impossible de répondre à cette exigence des consommateurs, qui ouvre de nouvelles opportunités commerciales à tous.

Pour répondre à ce nouveau besoin d'installer différentes extensions de partenaires dans un même dossier, nous devons nous assurer qu'elles ne partagent pas le même nommage.

Dans cette optique, Sage utilise le concept d'identifiant unique.

Les extensions de code fournies avec la version 7 permettent à chaque partenaire de bénéficier sur demande :

• d'un identifiant unique, généralement sous la forme d'un code alphanumérique à quatre chiffres,
• d'une plage de menus locaux et de tables diverses.

Cet identifiant est à indiquer en tête de chaque nom que vous créez dans le dictionnaire et dans vos programmes. Par exemple, XX12.

Cette règle de nommage concerne tous les éléments du dictionnaire qui utilisent une codification alphanumérique tels que les écrans, les classes, les représentations, les codes d'activité, les actions, le code source, etc.

Vous devez appliquer ces conventions pour toutes les clés, abréviations et paramètres des éléments.

Les nouvelles plages de dénomination deviennent donc :

• couche standard : A-V(A étant le module superviseur),
• couche verticale :
  • add-ons : X***(l'identifiant est unique - si les règles de nommage sont respectées, il n'y a pas de conflit de nomenclature),
  • assets : Y (Vous pouvez rencontrer des conflits si vous installez différents assets dans un même dossier),
• couche spécifique : Z (Les éléments sont spécifiques au client, aucun conflit à gérer).

Les plages 13000-13999 et 18000-29999 sont réservées aux menus locaux et aux tables diverses. Une plage dédiée, en fonction de vos besoins, peut vous être réservée sur demande.

L'équipe Sage Global Product Delivery est chargée de l'attribution des codes après une demande de partenaire.

Les codes sont stockés dans une base de données unique afin d'éviter toute double attribution.

Les données administratives ( authoring, badges, éléments de menu, etc.) sont stockées dans la base de données MongoDB.

Chaque composante des données administratives doit également être unique et inclure l'identifiant unique (en commençant par celui-ci ou en l'incluant dans certains cas expliqués plus bas).

Depuis la mise à jour 8, nous encourageons vivement tous les partenaires à utiliser le Factory ID pour étiqueter leurs éléments. Le Factory ID remplit la même fonction que le code d'activité pour les composants stockés dans la base de données MongoDB (voir la section Factory ID).

Si vous avez créé une extension avant la mise en place de ces règles, vous devez la renommer avant de la déplacer dans le programme d'add-ons. Ce programme vous offre de nouvelles opportunités commerciales.

Lorsque vous développez une nouvelle extension, appliquez immédiatement les règles de nommage et de développement des extensions.

Des conflits peuvent survenir si vous faites une installation dans la couche verticale qui ne respecte pas les règles de nommage de certains add-ons.

Vous devez traiter ce problème directement dans le projet où le conflit survient. Les conflits ne peuvent être anticipés.

Sage souhaite promouvoir les add-ons et demande à ce que les codes d'assets soient renommés.

À titre d'exemple, l'identifiant unique du Sage Portugal est XX04. L'ensemble de leurs développements doit commencer par XX04.

A la demande, Sage fournit à chaque partenaire une plage de menus locaux et de tables diverses adaptés à vos besoins. Par exemple, cette plage est de 13220-13259 pour le SagePortugal.

Les paragraphes suivants illustrent la procédure à suivre pour l'application des règles de nommage.

Éléments ajoutés dans une entité standard

Lorsque vous ajoutez des champs dans une entité standard telle qu'un écran :

• le nom des champs doit débuter par votre identifiant,

• vous devez définir un code d'activité, qui commence également par votre identifiant, pour chaque champ ajouté.

Dans la capture d'écran ci-dessous, X1QT correspond à l'identifiant unique à quatre chiffres du partenaire.

Pour faciliter l'identification, vous pouvez utiliser la convention de nommage suivante pour les champs que vous créez et qui viennent compléter des éléments de dictionnaire standard (tables, écrans, etc.) et qui n'existent pas encore dans l'application. Commencez par l'identifiant, suivi par un tiret bas (underscore).

Dans notre exemple, ce pourrait être X1QT_MAX.

Nouvelle entité définie dans le dictionnaire

Pour une nouvelle entité, telle qu'une table ou une classe :

• le nom et l'abréviation doivent commencer par votre identifiant,
• vous devez définir un code d'activité qui commence par votre identifiant sur l'élément.

Pour les sous-éléments, comme les colonnes :

• vous pouvez utiliser une codification libre. Elle n'entrera pas en conflit avec les autres extensions des partenaires, dans la mesure où elles appartiennent à votre entité.
• Vous n'avez pas besoin de les protéger avec un code d'activité car le code défini au niveau supérieur les protège.

La codification libre des colonnes facilite l'utilisation de l'affectation des classes, ce qui simplifie le codage.

Menus locaux et tables diverses

Sage attribue aux partenaires une plage de menus locaux et de tables diverses à utiliser pour le développement.

Utilisez les valeurs figurant dans cette plage et définissez des codes d'activité commençant par votre ID pour tout nouvel élément que vous créez.

Code source

Le nom de tous les scripts que vous créez doit commencer par votre identifiant.

Données d'administration

Cette catégorie comprend tous les éléments stockés dans la base de données MongoDB.

La plupart de ces éléments sont fournis aux clients en tant que composante de leur add-on. Sage souhaite éviter tout conflit de nommage avec d'autres éléments en provenance d'autres extensions partenaires lorsque vous installez votre package sur le site d'un client.

Pour cela, il suffit d'inclure votre identifiant unique dans le nom. Il peut être placé au début du nom ou à l'intérieur de celui-ci.

Vous pouvez utiliser un Factory ID depuis l’update 8. Factory ID vous permet d'étiqueter vos propres articles et de les protéger contre toute modification, à moins d'être connecté avec le même Factory ID.

Factory ID

Depuis l’update 8, vous pouvez attribuer un Factory ID à toutes les administrations.

Pour activer cette fonctionnalité, vous devez modifier le fichier nodelocal.js et autoriser Factory ID.

Cela présente deux avantages :

• vos développements sont protégés de toute modification client. Ces derniers ne peuvent que les dupliquer et les renommer en cas de besoin,

• vous pouvez facilement extraire les éléments liés à un Factory ID en un seul patch.

Paramétrer le Factory ID partenaire

En tant que partenaire, vous pouvez définir votre Factory ID dans un profil de sécurité si votre fichier nodelocal.js l'autorise.

Un utilisateur ayant ce profil de sécurité peut marquer des données comme étant livrées.

Vous pouvez le faire sur les entités principales du module d'administration. Vous pouvez également marquer des pages personnalisées comme étant livrées.

Sage applique cette méthode pour sécuriser les données livrées et éviter les mises à jour incorrectes de la part du client. Vous pouvez dupliquer vos données à l'aide du bouton Enregistrer sous, mais vous ne pouvez ni les modifier ni les supprimer.

Dans l'exemple ci-dessous, les éléments sont marqués d'un Factory ID et d'un propriétaire associé. Dans cette situation, le propriétaire est Sage.

Nommage des données d'administration - Meilleures pratiques

Cette section détaille les principales catégories de données que vous pouvez créer.

Pour les types de données qui ne figurent pas dans cette liste, l'objectif reste le même : choisir un nom qui évite tout conflit lors de l'exécution de l'installation dans un dossier client où d'autres extensions partenaires sont susceptibles de se trouver.

La meilleure solution consiste à faire figurer votre identifiant unique dans le nom.

Entrées de menu, modules et sous-modules de menu

Il existe deux façons de créer ces données ou entités :

• une création directement à partir de l'entité Syracuse,
• l'outil d'import.

Les règles sont adaptées pour être cohérentes.

L'outil d'import crée des entrées de menu uniquement pour les fonctions classiques et les gadgets V6.

Depuis l’update 9, la règle de nommage pour créer des éléments personnalisés ou verticaux est la suivante. FUNCTION est le code de la fonction.

• SPE_X3_ERP_FUNCTION pour les fonctions Sage X3 personnalisées
• SPE_X3_HRM_FUNCTION pour les fonctions Sage X3 HR & Payroll personnalisées
• VER_X3_ERP_FUNCTION pour les add-ons ou fonctions verticales Sage X3
• VER_X3_HRM_FUNCTION pour les d'add-ons ou fonctions verticales Sage X3 HR & Payroll

Vous n'avez pas besoin d'ajouter votre identifiant unique, car le nom de la fonction devrait déjà l'inclure.

La différence entre le nommage vertical et le nommage spécifique lors de l'importation est liée au paramètre utilisé lors du lancement de la copie :

• si le rôle est lié à un profil de sécurité pour lequel un Factory ID a été défini, la case à cocher Définir les éléments comme importés comme livrés se trouve sur la page de démarrage.
  si cette case est cochée, le nommage du préfixe VER_ est utilisé,
• sinon, la règle de nommage appliquée est le préfixe SPE_.

Pendant l'exécution de cet outil, un seul type de nommage est utilisé, indépendamment de la façon dont les fonctions sont nommées. Par exemple :

• VER_X3_ERP_ZFUNC pourrait être créé en import si la case est cochée, même si la normalisation des fonctions verticales ne doit pas utiliser Z comme préfixe.
• SPE_X3_ERP_XFUNC pourrait être créé en import si la case n'est pas cochée, même si la normalisation des fonctions spécifiques ne doit pas utiliser le préfixe X.

Pour conserver une cohérence générale, appliquez les mêmes règles si vous créez directement un élément de menu pour une fonction classique au lieu d'utiliser l'outil d'import.

Pour chaque fonction Syracuse que vous ajoutez, aucune fonction d'import ne créé d'entrée à votre place. Vous devrez créer votre propre entrée de menu, sous-module ou module de menu.

La normalisation n'est pas encore définie, mais vous devriez :

• inclure votre identifiant unique dans le code,
• inclure le nom de votre add-on dans le titre,
• utiliser le Factory ID pour étiqueter l'élément.

Personnalisation de pages

Lorsque vous personnalisez vos pages, vous devez fournir :

• un code qui inclut votre identifiant unique,
• un titre et une description. Le titre peut contenir le nom de votre add-on car c'est la seule information visible par l'utilisateur final. Le code n’est pas affiché,
• le paramètre Enregistrer sous. L'option Livré n'est disponible que si :
  • la fonction EnablePartnerID est configurée,
  • votre profil de sécurité est défini par un ensemble de Factory ID.

  Le Factory ID associé à votre profil de sécurité est défini pour cet élément. Vous n'avez pas à saisir de valeur.

Autres données d'administration

Vous pouvez soit :

• faire commencer votre codification avec votre identifiant unique,
• ou inclure votre identifiant unique à n'importe quel emplacement dans la clé.