API V5

Votre guide d'intégration V5 !

Introduction

La passerelle de traçabilité V5 permet un échange de données bidirectionnel entre la gamme de produits de traçabilité V5 et d'autres solutions. La passerelle est très flexible, permettant un déploiement rapide avec de nombreux systèmes ERP et externes différents, permettant aux clients d'intégrer efficacement l'ensemble de leur usine. La gamme de produits V5 dispose d'une API étendue pour une utilisation en intégration.

Ce guide fournira un aperçu détaillé de la façon d'utiliser les différentes méthodes d'importation et d'exportation de données. Il détaillera également chaque entité pouvant être importée et les champs possibles pour ces entités.

La passerelle peut être utilisée de 2 manières principales :

Via une API REST d'interface Web utilisant des fichiers JSON ou XML.
Via le partage direct de fichiers avec des documents CSV ou XML.

Ces deux méthodes seront examinées dans ce guide, ainsi que des exemples pour les principaux domaines d'intégration de données.

Table des Matières

Que fait la passerelle V5 ?
Exemple de diagramme de flux de données
Guides d'intégration
Documents de référence de l'intégration V5
Méthodologie – API V5
Méthodologie – Partage de fichiers CSV
Fréquence et séquence
Contactez-Nous

1. Que fait la passerelle V5 ?

Le service d'intégration V5 Traçabilité peut être déployé pour couvrir une gamme de points de données, qui peuvent être entièrement personnalisés par chaque client en fonction de ses besoins. Ces exigences seront discutées lors des phases initiales de mise en œuvre de la traçabilité V5.

Selon les exigences du client, la traçabilité V5 peut être configurée pour intégrer un nombre illimité de domaines, tels que la formulation/les nomenclatures, la planification des travaux, les commandes d'achat et de vente, les niveaux et les emplacements des stocks.

2. Exemple de diagramme de flux de données

Le diagramme de flux de données ci-dessous illustre l'intégration transparente du système ERP hôte et de la traçabilité V5. De la réception et la gestion des stocks à la formulation de lots, la création de produits, la préparation des commandes et l'expédition. La passerelle V5 permet aux entreprises de rationaliser efficacement leurs opérations, en améliorant la visibilité de la production et en corrigeant les erreurs du processus de traçabilité.

3. Guides d'intégration

Dans cette section, vous trouverez des guides spécifiques pour l'intégration de modules de traçabilité V5 spécifiques :

Pour les principaux modules qui présentent généralement une intégration bidirectionnelle :

Pour les modules mineurs qui ne proposent que des options d’importation :

Pour obtenir de l'aide sur l'installation et la mise à jour de l'API V5, veuillez consulter la documentation suivante :

Guide d'installation et de mise à jour de l'API V5

Pour des exemples de déploiement d'intégration, veuillez consulter nos guides pour des solutions ERP spécifiques ci-dessous :

4. Documents de référence de l'intégration V5

Tout au long de ce guide des méthodes d'intégration de V5 Traçabilité, nous utiliserons régulièrement deux documentations pour nous aider. Ceux-ci sont tous deux utiles quelle que soit la méthode d'intégration que nous utilisons. Ceux-ci sont:

Le Fiche de travail d'intégration V5 qui contient des informations utiles et des modèles pour les modules les plus couramment intégrés.
Le Manuel API V5, qui peut être utilisé pour identifier des URI d'importation/exportation spécifiques et fournir un guide complet pour chaque classe de données utilisée par l'API V5.
Tout au long des guides API de cette section, des références seront faites à points de terminaison transactionnels et de journalisation. Une liste complète de ceux-ci peut être trouvée en suivant le lien.

5. Méthodologie – API V5

Si vous utilisez cette méthode, l'API V5 sera installée en tant que service Web pour faciliter le transfert de données. À partir de là, les transactions sont gérées par les différentes classes de modules disponibles.

Pour en savoir plus sur ces classes, les différents points de terminaison/URI, ainsi que des informations sur les différentes classes de base de données que nous allons traiter lors de l'utilisation de l'API V5, nous pouvons utiliser à la fois le 'Feuille de travail de mappage d'intégration V5' et le Site Web de l'API V5 pour nous assister. De là, nous pouvons utiliser l'explorateur de packages en haut à gauche de cette fenêtre pour naviguer dans les différentes sections du manuel de l'API.

Nous utiliserons ces sections pour créer des exemples lorsque nous aborderons les différents aspects de l'intégration des données ci-dessous.

Une fois installés, les points de terminaison de l'API sont accessibles via un navigateur ou un client REST à :

http://{hostname:port}/V5-API/api

Le module IntegrationImport a un chemin de /integrate/import/

Le module IntegrationExport a un chemin de /integrate/export/

Le chemin du module 'Transactions' est /integrate/export/transactions/

Chaque méthode a son propre chemin répertorié dans le répertoire de l'API V5 en tant que ‘Target URI’. Cela peut être ajouté à la fin des chemins ci-dessus afin d'exécuter la méthode.

Chaque description de méthode contient également une ‘request type’, qui indique s'il s'agit d'une requête GET ou POST plus l'URI pour cette méthode donnée.

Toutes les requêtes GET ou POST seront traitées au format JSON. Tous les champs et objets sont définis dans le package de base de données que vous pouvez trouver via le forfait de services.

5.1. Demandes d'exportation/obtention

Comme mentionné ci-dessus, le module d'exportation de l'API V5 a un chemin de :

http://{hostname:port}/V5-API/api/integrate/export/

Donc, en réalité, cela ressemblerait à quelque chose comme (si vous interagissez via une instance installée localement de l'API V5):

http://127.0.0.1:8080/V5-API/api/integrate/export/

Ce qui viendra après cela dépend des données que nous voulons extraire de la V5. Nous ferions alors référence au package de services, en utilisant les fenêtres à gauche de la fenêtre principale de l'API pour sélectionner le package de services, suivi de « IntégrationExport » ci-dessous.

Nous pouvons également utiliser le lien des services sur la page d'index, qui chargera ensuite le résumé de la classe pour ce package, où nous pourrons ensuite choisir la classe 'IntegrationExport'.

Nous verrons ensuite l'URI cible d'exportation (1) ainsi qu'une liste des points de terminaison disponibles pour la classe de module d'exportation. Nous pouvons voir tout cela en détail en cliquant sur le constructeur 'IntegrationExport' (2), ou nous pouvons utiliser le ‘Method Summary’ tableau ci-dessous (3) pour trouver rapidement le point final souhaité. Nous pouvons également voir l'URI cible de ce module en haut de la page, il ne nous reste donc plus qu'à identifier les objets, champs et valeurs requis.

Prenons donc la première entrée dans le tableau récapitulatif de la méthode ici, ‘Batch’. Cliquer sur le lien dans la colonne de droite (4) nous amènera directement au point final que nous voulons connaître.

Cela nous fournit les informations dont nous avons besoin, y compris les données qui seront rappelées, le type de requête et, plus important encore, l'URI cible de la requête.

Nous savons donc maintenant que si nous voulons extraire un lot de l'API V5, le point de terminaison que nous aurions besoin d'atteindre serait :

http://127.0.0.1:8080/V5-API/api/integrate/export/batch/{batchNumber}

Voyons rapidement comment cela fonctionnerait en pratique. Nous pouvons commencer par trouver un lot que nous voulons extraire via l'API, allons-y pour le lot '50009622' que nous pouvons voir ici dans Control Center.

En utilisant ce que nous avons appris ci-dessus, nous pouvons ensuite compléter l'URI dans le client REST en tant que tel :

L'exécution de ce processus maintenant générera alors un fichier JSON détaillé pour ce lot, qui pourra ensuite être consommé et analysé par l'application cliente. Un retour typique pour cette demande pourrait ressembler à ceci.

Dans de nombreux cas où le pluralisme est applicable aux points de terminaison que nous adressons, par exemple ici, le lot peut devenir des lots, nous pouvons l'utiliser pour appeler une liste de lots avec le ‘export/batches’ URI.

5.2. Demandes d'importation/envoi

Comme mentionné ci-dessus, le module d'importation de l'API V5 a un chemin de :

http://{hostname:port}/V5-API/api/integrate/import/

Ce qui suivrait dépendrait des données que nous cherchons à importer via l'API. Nous reviendrions à la section des forfaits de services du Manuel API et cliquez sur 'IntégrationImporter' (1) cette fois.

Ceci est présenté de la même manière sur la page des exportations, avec l'URI d'importation (2), le lien vers le haut des pages de résumé ci-dessous (3) et le tableau récapitulatif des méthodes (4) où nous pouvons voir tous les points de terminaison disponibles. .

Comme auparavant, nous aurions juste besoin de trouver le point de terminaison pertinent pour les données que nous souhaitons publier sur le système via l'API.

Notez que la plupart des points de terminaison POST d'importation attendent un tableau afin que plusieurs enregistrements puissent être envoyés dans une seule demande. Cela peut être vu en examinant les types de paramètres pour les points de terminaison d'importation sous le ‘Method Summary’.

Prenons les matières premières comme exemple ici :

Ce que cela nous dit ici, c'est que nous pouvons utiliser ce point de terminaison pour importer des listes de produits/ingrédients qui peuvent ensuite être utilisés pour la formulation. L'URI que nous utiliserions pour cela serait :

http://127.0.0.1:8080/V5-API/api/integrate/import/commodity

Nous pouvons voir ce point de terminaison en cours d'utilisation ci-dessous, ainsi qu'un exemple de fichier d'importation très basique au format JSON :

Pour nous aider à structurer un fichier d'import JSON, nous pouvons utiliser le lien vers la section des packages de base de données concernés du manuel de l'API présent sur le résumé du service :

Ou nous pouvons naviguer manuellement vers la section appropriée en sélectionnant la section récapitulative de la classe de base de données dans la Page d'accueil de l'API.

Si nous naviguons vers la page de classe de base de données ci-dessous pour ‘Commodity’, nous pouvons comment structurer ou fichier JSON. Par exemple, si nous voulons définir un code marchandise lors de l'utilisation de cet URI, ce serait ‘code’, et de même pour la description de la marchandise, ce serait ‘description’.

Notez alors comment ces champs se trouvent tout à gauche de l'exemple de fichier JSON ci-dessus, ainsi que d'autres champs que nous pouvons voir sur la capture d'écran tels que ‘defExpiryDays’. Nous pourrions également ajouter le coût par défaut du produit à notre fichier, et en vérifiant ci-dessous, nous pouvons voir que ce serait simplement ‘cost’ (1). Notez également que tout ce qui est répertorié ici comme un ‘primary key’ (2) est un champ obligatoire pour ce point de terminaison, c'est-à-dire que le fichier ne sera pas importé s'il n'est pas présent.

Nous pouvons également traverser différents niveaux de l'API à partir de cette classe de base de données, alors voyons comment nous pouvons le faire pour inclure plus d'informations sur nos produits ‘units’.

Vers le bas de cette page, nous rencontrerons ‘WeightUnit’, que nous pouvons utiliser comme classe imbriquée dans l'URI de la marchandise.

Cela nous donne notre classe de base de données pour ‘units’, qui peuvent se situer au même niveau que les autres classes que nous avons déjà définies. Pour découvrir quelles données nous pouvons imbriquer ici, nous pouvons cliquer sur ‘WeightUnit’ ici pour parcourir les définitions de cette classe.

Comme nous pouvons le voir, il n'y a que 3 points de données dans cette classe, et dans notre exemple JSON, nous les utilisons tous, ‘code’, ‘description’, et ‘conversionRate’. Ces 3 points de données seraient imbriqués dans le ‘units’ champ, comme indiqué.

Si nous exécutons ce fichier JSON comme ci-dessus, nous verrons (selon le client que nous utilisons) une réponse de l'API, et nous pourrons également voir cette marchandise importée dans notre 'Matières premières' dans le centre de contrôle.

5.3. Insérer ou mettre à jour ?

Lorsque vous utilisez la fonction POST pour atteindre les points de terminaison de l'API V5, cela peut mettre à jour ou insérer un enregistrement. Ce qui se passe ici est défini par la clé primaire que nous essayons de publier.

Si nous reprenons notre exemple de marchandise ci-dessus, nous avons vu dans les définitions de classe de la base de données que le code de la marchandise est sa clé primaire. Lorsque nous publions, si ce code existe déjà, nous mettrons à jour l'enregistrement de ce produit avec les nouvelles valeurs incluses à ce niveau de classe.

A l'inverse, si le code n'existe pas actuellement dans la base de données V5, alors un nouvel enregistrement sera créé.

Cependant, si nous regardons notre ‘units’ classe imbriquée, notez que bien que nous puissions insérer de nouvelles données d'unité si la clé primaire de cette classe n'est pas déjà présente, nous ne pouvons pas mettre à jour les unités existantes en utilisant la ‘commodity’ point final. Au lieu de cela, nous devions nous attaquer au ‘import/unit’ URI à la place.

5.4. Marqueurs d'exportation

L'API V5 utilise des marqueurs d'exportation pour différencier les données qui ont ou n'ont pas déjà été exportées vers le système ERP d'un client. Par défaut, cette option est activée pour faciliter l'exportation de données que l'ERP externe n'a pas encore vues, et une fois marquées comme exportées dans la base de données V5, ces données ne seront pas incluses dans les exportations futures.

Cela peut cependant être désactivé en fonction de la préférence du client. Cela peut également être désactivé si le système ERP utilisé peut renvoyer des marqueurs d'exportation à l'API V5 pour reconnaître qu'il a déjà reçu les données en question.

Dans cette situation, un accusé de réception est utilisé pour informer l'API V5 que les données ont été reçues, le point final qui peut être utilisé pour contrôler cela est documenté. ici.

Si ni l'API V5 ni l'ERP ne sont configurés pour fournir des marqueurs d'exportation, alors, selon le point de terminaison utilisé, cela pourrait potentiellement renvoyer une grande quantité de données. Dans ces cas, nous pouvons utiliser des paramètres URI pour filtrer la quantité de données exportées.

5.5. Paramètres URI

L'API V5 utilise également divers paramètres URI qui peuvent être utilisés pour affiner davantage nos demandes du système.

Nous pouvons voir si ces paramètres sont disponibles pour nos points de terminaison en vérifiant les résumés de méthodes sous notre service souhaité. Si nous pouvons voir ‘int’ suivi d'un paramètre, nous pouvons alors utiliser ce paramètre pour filtrer les résultats que nous recevrons de l'API.

Par exemple, nous avons vu plus haut que cela fonctionne pour ‘batch’ en nous permettant de filtrer par numéro de lot.

D'autres exemples pourraient inclure l'extraction de journaux de lots par date, où nous pouvons utiliser ‘batch_system_logs/filterFrom/{filterDate}’ (en utilisant les conventions de datation d'époque).

5.6. Journaux, transactions et descripteurs système

Pour de nombreux modules pouvant être intégrés via l'API V5, il est souvent plus pratique de récupérer des informations à partir des points de terminaison des transactions et des journaux. Certains d’entre eux peuvent être utilisés à plusieurs fins (comme les « journaux système »), tandis que d’autres sont plus personnalisés pour des modules spécifiques (tels que les « transactions de vente »).

Ces points de terminaison utilisent descripteurs de système pour indiquer que certains événements se produisent (réception d'une marchandise, consommation d'un ingrédient pour la production, etc.) et sont particulièrement utiles pour maintenir l'exactitude des stocks dans le système V5.

Pour examiner ces points de terminaison et les informations qu'ils renvoient/les modules pour lesquels ils sont utiles, cliquez sur ici.

6. Méthodologie - Partage de fichiers CSV

La méthode de partage de fichiers V5 utilise des fichiers 'en-tête' csv et csvh pour effectuer des échanges de données avec V5 Traçabilité. Pour ces échanges, nous utiliserons des fichiers « d'en-tête » pour déterminer l'ordre des données pour les importations et les exportations, puis nous importerons ou recevrons un csv exporté qui suit cet ordre. Nous pouvons voir comment cela fonctionnerait dans la pratique ci-dessous.

6.1. Classement des fichiers de données et d'en-tête

Que nous importions ou exportions des données à l'aide de la méthode de partage de fichiers csv, nous utiliserons des fichiers d'en-tête pour déterminer l'ordre des données. En ce qui concerne la façon dont nous pouvons les structurer, nous pouvons ici utiliser à la fois le 'Feuille de travail de mappage d'intégration V5' et le web Manuel API pour nous aider avec ça. Prenons un exemple ici pour un ‘Commodities’ importer à partir de la feuille de calcul.

Comme nous pouvons le voir ici, SG a déjà structuré une disposition d'en-tête de base ici, et si nous regardons dans le manuel de l'API à cette classe de base de données particulière, nous pouvons voir que la majorité des champs ici existent dans cette classe, nous permettant d'utiliser simplement ‘code’, ‘cost’, ‘bulkUnit’ etc. tels qu'ils sont définis ici.

Notez que, comme lorsque nous cherchions à structurer nos fichiers JSON ci-dessus, la clé primaire (code) doit être inclus.

Nous pouvons également parcourir les classes de base de données d'une manière similaire à celle que nous avons vue lors de la structuration de l'importation JSON ci-dessus. Nous pouvons le voir dans notre exemple ci-dessus avec ‘units.code’. Dans le ‘Commodity’ classe nous avons la ‘WeightUnits’ classe (définie comme ‘units’).

Suite à ce lien vers le ‘WeightUnit’ class va nous montrer que pour définir le code de l'unité de poids, c'est ‘code’ dans cette classe, donc pour traverser à cela de notre ‘Commodity’ le point de départ serait ‘units.code’.

On peut parcourir autant de niveaux qu'on veut ici, il suffit de les relier dans le manuel de l'API.

Nous ferions de même pour structurer les en-têtes que nous utiliserions pour les exportations, en utilisant les définitions de classe de base de données appropriées pour identifier les données que nous voulons recevoir du système et dans quel ordre.

Les fichiers d'en-tête doivent être construits sous forme de fichiers csv, avec 1 valeur dans chaque cellule de la ligne supérieure jusqu'à ce que nous ayons défini toutes les données que nous voulons importer ou exporter. Ce fichier csv doit ensuite être enregistré puis son extension modifiée pour être un ‘csvh’ fichier (l'affichage des extensions de fichier dans Windows doit être activé pour ce faire).

Toute modification du fichier csvh doit être effectuée après l'avoir retransformé en fichier csv et l'avoir modifié dans ce format.

Les en-têtes utilisés pour les importations doivent être placés dans :

<installdir>\SG Control Center\gateway\import\column_defs

Les en-têtes utilisés pour les exportations doivent être placés dans :

<installdir>\SG Control Center\gateway\export\order

Nous pouvons maintenant voir comment nous procéderions pour effectuer nos importations et nos exportations.

6.2. Importations

Une fois que nos fichiers d'en-tête pertinents sont en place, nous devons compléter notre fichier csv pour l'importation.

Comme déjà évoqué, les données de notre fichier csv doivent respecter la même structure que son fichier d'en-tête correspondant, c'est-à-dire que les données correctes doivent se trouver dans la bonne colonne, pour que l'importation réussisse. Pour rester dans notre exemple de marchandise, nous pouvons voir que dans cet exemple ci-dessous, nous avons inclus les données d'en-tête pour nous aider à saisir les données. Cela n'a pas besoin d'être inclus cependant (voir 'Ignorer les en-têtes' ci-dessous).

Une fois que nous avons configuré cela, nous pouvons continuer à remplir le csv pour inclure tous les produits que nous voulons importer.

Une fois le csv terminé, les importations peuvent ensuite être effectuées en déposant les fichiers csv correctement formatés et nommés dans ‘\SG Control Center\gateway\import’. Les conventions de dénomination de ces fichiers sont définies sur la feuille de travail de mappage d'intégration V5, donc pour les produits de base, nous pouvons voir qu'il s'agit de :

Ainsi, par exemple, notre nom de fichier pourrait être nommé 'commodity-0530231803.csv pour nous dire que cela a été importé le 30^th Mai 2023 @ 18:03. Il n'y a pas de préférence de commande de date/heure définie, donc SG recommande d'utiliser le format qui convient le mieux à chaque client ici (cela peut finir par être déterminé par l'ERP externe utilisé).

Après avoir déposé nos fichiers dans le bon dossier, Control Center les traitera automatiquement, à condition que les importations soient activées dans la passerelle. Le système fournira un dialogue pour nous informer si le processus a réussi ou non. De plus amples informations à ce sujet, avec les journaux, peuvent être trouvées dans la section "Passerelle" du Centre de contrôle.

Les fichiers peuvent également être importés manuellement à partir d'autres emplacements en cliquant avec le bouton droit de la souris sur l'icône du centre de contrôle dans le système et en choisissant Gateway > Import File.

Cela ouvrira alors une boîte de dialogue dans Control Center pour sélectionner le fichier csv approprié.

Dans la passerelle elle-même, nous pouvons ensuite définir des options pour le processus d'importation :

Les paramètres ici peuvent être définis comme suit :

Importation activée – active l'importation, permettant à la passerelle d'analyser le dossier d'importation pour les csv au fur et à mesure qu'ils y sont déposés.
Insérer des entités enfants – permet à la passerelle de créer dynamiquement des entités internes si elles sont liées dans le fichier csv. Un bon exemple de ceci pourrait être une importation de formule qui répertorie les produits qui ne sont pas déjà présents dans la base de données. La passerelle créera ces entités « enfants » pour nous dans ce cas, à condition que la clé primaire de la marchandise (code) soit fournie.
Ignorer les en-têtes – force la passerelle à ignorer la première ligne (ligne) d'un csv importé. Ceci est utile si le fichier d'en-tête est inclus dans le fichier d'importation csv.
Niveau de validation – définit la manière dont les données sont validées lorsqu'elles sont importées par la passerelle. Il y a 2 options ici :
- Avertir – Si une erreur existe dans un fichier et qu'une ligne ne peut pas être importée, le système vous en informera mais il continuera à essayer de traiter le reste du fichier.
- fausse couche – Si une erreur existe dans un fichier et que la ligne ne peut pas être importée, le système interrompra le processus et vous informera de l'erreur.

Les modifications apportées aux paramètres peuvent ensuite être appliquées en haut à droite de ce panneau. Le centre de contrôle doit être redémarré pour que les modifications prennent effet.

6.3. Exportations

L'exportation via la méthode de partage de fichiers csv est en grande partie gérée par le fichier d'en-tête et les informations demandées au système. Si nous les structurons correctement à l'aide du manuel de l'API, nous devrions recevoir toutes les données souhaitées dans le bon ordre.

Dans la passerelle elle-même, nous pouvons également définir des options pour le processus d'exportation :

Ici, nous pouvons utiliser les cases à cocher fournies pour sélectionner les données que nous souhaitons exporter, en fonction des points de données que nous souhaitons voir.

Notez que les classes de base de données de départ ici, telles que ‘BatchConsumption’ et ‘SystemLogs’ sont différents de ceux avec lesquels nous commencerions pour les importations, mais à condition que nous soyons capables de naviguer avec succès dans le manuel de l'API pour ces classes, nous pouvons produire un fichier d'en-tête approprié.

Une fois que nous avons sélectionné ce que nous voulons exporter, il suffit alors d'entrer un intervalle d'exportation (en millisecondes) en haut à gauche et d'appliquer cette valeur (0 n'exportera jamais) en haut à droite. Le centre de contrôle doit être redémarré pour que les modifications prennent effet.

Les fichiers csv exportés seront placés dans ‘<installdir>\SG Control Center\gateway\export’ by default.

7. Fréquence et séquence

Quelle que soit la méthodologie utilisée pour l'intégration avec V5 Traçabilité, la fréquence et le niveau d'automatisation des importations et des exportations de données est un élément du processus qui peut être construit pour répondre aux exigences de chaque client.

Cela peut être fait manuellement par le client ou automatisé pour capturer la sortie d'un ERP externe à partir d'un emplacement spécifique sur le serveur du client.

Un ordre d'importation spécifique peut également être imposé à ce stade, ainsi, par exemple, nous pourrions importer une nomenclature avant un ordre de travail relatif à cette nomenclature. Nous pourrions le faire en chargeant les fichiers dans l'ordre dans le répertoire d'importation ou les points de terminaison URI de l'API.

Comme indiqué ci-dessus, nous pouvons également configurer la passerelle pour qu'elle exporte à des intervalles spécifiques afin de renvoyer les données au système ERP.

Les importations et les exportations peuvent être gérées en temps quasi réel ou effectuées à des intervalles définis. En utilisant la route API, les importations et les exportations peuvent être plus facilement gérées en temps quasi réel. La fréquence d'importation pour la méthode de partage de fichiers csv dépend de la solution ERP/middleware individuelle mise en œuvre, la fréquence d'exportation étant gérée via Control Center comme décrit ci-dessus.