Test - Guide Implémentation message TRC (tracing)
Guide d’implémentation message XML Request TRC - Tracing
Sommaire
1. Introduction
Ce document présente le guide de message xml Request « Tracing » qui offre un service de récupération des statuts de la marchandise dans le PCS Ci5.
1.1 Objet du message
Ce message a pour but la création / mise à jour des entités Tracing.
1.2. Objet du guide d’implémentation
Le guide d’implémentation de « Tracing » présente le message de tracing/mise sous surveillance au format Ci5 utilisant le langage XML (eXtensible Mark-up
Language).
Ce document décrit l’ensemble des données et règles nécessaires à la constitution et à l’envoi d’un message de tracing par l’utilisateur vers Ci5.
2. Diagramme des flux
Le message d’intégration de tracing appartient au flux d’information marchandise export/import.
3. Présentation du message
3.1. Modèle fonctionnel
D’un point de vue fonctionnel, un message de tracing est constitué de plusieurs groupes fonctionnels différents, un groupe fonctionnel étant un ensemble de
données ayant une portée fonctionnelle similaire. Ainsi, le message de tracing est composé des groupes fonctionnels suivants :
Ces groupes fonctionnels ne sont pas obligatoirement présents dans le message. Certains peuvent être présents plusieurs fois. Ceci est représenté dans le
modèle ci-dessous.
Message tracing
3.2. Diagramme de branchement
Le diagramme de branchement présente la manière dont sont ordonnées les balises XML afin de décrire les groupes fonctionnels présentés dans le schéma du
message de tracing.
Diagramme de branchement Le guide d’implémentation du message tracing présente la façon dont doit être implémenté chaque groupe fonctionnel.
L’implémentation de chaque groupe fonctionnel selon le langage XML amène à présenter les données les constituant sous forme d’un ou plusieurs éléments.
Chacun de ces éléments est décrit plus précisément à l’aide d’attributs. Ainsi, chaque groupe fonctionnel sera décrit élément par élément et chaque élément sera détaillé avec l’ensemble de ses attributs comportant une définition, un statut, un format, un marqueur, des règles et conditions ainsi que la précision de la valeur de l’attribut si celle-ci relève spécifiquement de Ci5.
Pour chaque élément, une deuxième page explicative précise son objet et développe les différentes règles et conditions auxquelles il est soumis.
Le statut de la donnée est décrit à l’aide de trois valeurs :
Un exemple d’implémentation est fourni pour chaque élément avec une séquence minimale et complète.
Pour conclure, un exemple de message est fourni en guise d’illustration.
3.3. Conditions d’intégration de tracing
3.3.1. Quels sont les tiers habilités à créer un tracing ?
Tous.
3.3.2. Quelles sont les conditions de création d’un tracing ?
La référence du tracing ne doit pas déjà être utilisée par un autre tracing de l’utilisateur.
3.3.3. Quelles sont les conditions de modification d’un tracing ?
Un tracing peut être modifié s’il est déjà existant en statut actif ou inactif.
3.4. Conditions d’intégration de rétro-tracing
3.4.1. Quels sont les tiers habilités à créer un rétro-tracing ?
Tous.
3.4.2. Quelles sont les conditions de création d’un rétro-tracing ?
Un tracing est dit « rétro-tracing » lorsque la date de début de surveillance est antérieure à la date de création du tracing. Les notifications des événements sélectionnés seront alors envoyées s’ils ont déjà eu lieu.
La référence du tracing ne doit pas déjà être utilisée par un autre tracing de l’utilisateur.
3.4.3. Quelles sont les conditions de modification d’un rétro-tracing ?
Un rétro-tracing ne peut pas être modifié. Un tracing existant ne peut pas modifier en rétro-tracing.
3.5. Mode de création/mise à jour
Le mode création/mise à jour du message devra être spécifié explicitement par l’intermédiaire du code action.
Le code action indique au PCS le traitement à opérer sur l’entité fonctionnelle contenue dans le corps du message.
- Création — Code action : CREATE ; Action effectuée dans Ci5 : Création de l’entité dans Ci5
- Modification — Code action : UPDATE ; Action effectuée dans Ci5 : Annulation et remplacement de l’entité
- Suppression — Code action : DELETE ; Action effectuée dans Ci5 : Suppression ou Invalidation de l’entité
Le code action est renseigné dans l’élément
3.6. Groupe fonctionnel « Entête message »
3.6.1. Elément
Groupe Fonctionnel : Entête message - Elément : 1/5 - Elément parent : Aucun - Cardinalité : 1..1
Syntaxe Minimale :
xml
- Identifiant de l’interchange — Statut :
o ; Format : AN..14 ; Marqueur : id - Identifiant du système émetteur — Statut :
o ; Format : AN..35 ; Marqueur : from - Identifiant du système destinataire — Statut :
o ; Format : AN..35 ; Marqueur : to
Objet de l’élément
L’élément « interchanges » introduit le contexte de l’échange de données entre Ci5 et le système partenaire. Il possède un identifiant attribué par le système émetteur et contient le nom des plates-formes émettrices et destinataires.
L’élément « interchanges » est utilisé afin d’assurer le suivi de l’intégration des messages dans Ci5.
Règles
L’élément « interchanges » est unique dans le fichier.
Les attributs identifiants, « from » et « to » de l’élément « interchanges » sont obligatoires, mais non contrôlés hors respect du format.
3.6.2. Elément
Groupe Fonctionnel : Entête message - Elément : 2/5 - Elément parent : Interchanges - Cardinalité : 1..1
Syntaxe Minimale :
xml
- Référence message — Statut :
o ; Format : AN..14 ; Marqueur : id - Identifiant de l’interchange de rattachement — Statut :
o ; Format : AN..14 ; Marqueur : icid - Horodatage — Statut :
o ; Format : AN..19 ; Marqueur : date ; Règles et conditions : Format date : jj/mm/aaaa hh:mn:ss
Objet de l’élément
L’élément « MessageSet » indique la présence d’un message dans l’interchange. Il possède un identifiant attribué par le système émetteur et contient l’identifiant de l’interchange auquel il se rattache ainsi que la date à laquelle il a été créé dans la plate-forme émettrice.
L’élément « MessageSet » est utilisé afin d’assurer le suivi de l’intégration des messages dans Ci5.
Règles
L’attribut identifiant de l’élément « MessageSet » est fourni par la plate-forme émettrice. Cette information est nécessaire pour assurer le suivi de l’intégration du message.
La valeur de l’attribut ‘icid’, « identifiant de l’interchange » de rattachement de l’élément « MessageSet », est identique à celle de l’attribut « id » dans l’élément « Interchanges ».
3.6.3. Elément
Groupe Fonctionnel : Entête message - Elément : 3/5 - Elément parent : MessageSet - Cardinalité : 1..1
Syntaxe Minimale :
xml
- Identifiant du trader Ci5 émetteur du message — Statut :
o ; Format : AN..9 ; Marqueur : tiersProf ; Valeur : Codification Ci5 - Code utilisateur de l’émetteur du message — Statut :
o ; Format : AN..9 ; Marqueur : user ; Valeur : Codification Ci5
Objet de l’élément
L’élément « Emetteur » précise fonctionnellement le rôle de la plate-forme émettrice et permet de réaliser son authentification et son habilitation à envoyer des messages de tracing à Ci5.
L’élément « Emetteur» est utilisé afin d’assurer le suivi de l’intégration des messages dans Ci5.
Règles
L’ensemble des attributs de l’élément « emetteur » sont codifiés et paramétrés dans Ci5.
3.6.4. Elément
Groupe Fonctionnel : Entête message - Elément : 4/5 - Elément parent : MessageSet - Cardinalité : 1..1
Syntaxe Minimale :
xml
- Identifiant du trader Ci5 émetteur du message — Statut :
o ; Format : AN..9 ; Marqueur : tiersProf ; Valeur : Codification Ci5 - Code utilisateur de l’émetteur du message — Statut :
o ; Format : AN..9 ; Marqueur : user ; Valeur : Codification Ci5
Objet de l’élément
L’élément « Destinataire » précise fonctionnellement le rôle de la plate-forme destinataire et permet de réaliser son authentification et son habilitation à recevoir des messages de tracing à Ci5.
L’élément « Destinataire» est utilisé afin d’assurer le suivi de l’intégration des messages dans Ci5.
Règles
L’ensemble des attributs de l’élément « Destinataire » sont codifiés et paramétrés dans Ci5.
3.6.5. Elément
Groupe Fonctionnel : Entête message - Elément : 5/5 - Elément parent : MessageSet - Cardinalité : 1..1
- — Marqueur : <Messages>
Objet de l’élément
L’élément « Messages » indique la présence d’un document dans l’élément « MessageSet ». L’élément « Messages» est utilisé afin d’assurer le suivi de l’intégration des messages dans Ci5.
3.7. Groupe fonctionnel « Entête document »
3.7.1. Elément
Groupe Fonctionnel : Entête document - Elément : 1/2 - Elément parent : Messages - Cardinalité : 1..1
Syntaxe Minimale :
xml
- Type du document — Statut :
o ; Format : AN..3 ; Marqueur : type ; Règles et conditions : Codification Ci5 ; Valeur : TRC - Numéro de réf. du document — Statut :
o ; Format : AN..17 ; Marqueur : id - Code fonction du document — Statut :
o ; Format : AN..6 ; Marqueur : action ; Règles et conditions : Codification Ci5 ; Valeur : CREATE= Création UPDATE= Modification DELETE=Invalidation
Objet de l’élément
L’élément « Request » contextualise le document faisant l’objet de l’intégration avec la précision d’un type, d’un identifiant et d’un code fonction.
Règles
Il est conseillé de renseigner l’attribut « id » avec la référence fonctionnelle du tracing, définie dans l’élément reference-tracing, attributs ref.
3.7.2. Elément
Groupe Fonctionnel : Entête document - Elément : 2/2 - Elément parent : Request - Cardinalité : 1..1
Syntaxe Minimale :
xml
- — Marqueur :
Objet de l’élément
L’élément « tracing» indique le début de la description du document.
3.8. Groupe fonctionnel « Références »
3.8.1. Elément
Groupe Fonctionnel : Références - Elément : 1/1 - Elément parent : tracing - Cardinalité : 1..1
Syntaxe Minimale pour le bloc BL :
xml
Syntaxe Minimale pour le bloc unité de manutention :
xml
- Référence du tracing — Statut :
o ; Format : AN..35 ; Marqueur : ref - Statut du tracing — Statut :
F ; Format : AN..3 ; Marqueur : statut ; Règles et conditions : ACT Par défaut ; Valeur : INA, ACT - Horodatage début période de surveillance — Statut :
o ; Format : AN..16 ; Marqueur : horodebut ; Règles et conditions : Format : Jj/mm/aaaa hh:mn - Horodatage fin période de surveillance — Statut :
o ; Format : AN..16 ; Marqueur : horofin ; Règles et conditions : Format : Jj/mm/aaaa hh:mn - Zone Ci5 sur laquelle est faite le tracing — Statut :
F ; Format : AN...4 ; Marqueur : zone-sic ; Règles et conditions : Code de communauté Ci5 ; Valeur : A compléter - Référence Unité de manutention (cargo) — Statut :
F ; Format : AN..20 ; Marqueur : refum ; Règles et conditions : Référence du cargo (conteneur, Roro, breakbulk, lot de dépotage, lot de groupage) - Référence BL — Statut :
F ; Format : AN..20 ; Marqueur : blref - Référence du booking — Statut :
F ; Format : AN..20 ; Marqueur : cbkref - Identifiant de l’unité de manutention (cargo) — Statut :
F ; Format : AN..13 ; Marqueur : amq ; Règles et conditions : Identifiant Ci5 - Référence dossier rattaché au cargo — Statut :
F ; Format : AN..20 ; Marqueur : Dossref
Objet de l’élément
L’élément « reference-tracing » indique quelles sont les références de l’entité à surveiller dans le PCS.
Règles
L’élément « reference-tracing » est présent une fois dans l’élément « tracing ».
L’attribut « ref» indique quelle est la référence tracing du partenaire.
Il ne peut y avoir plusieurs blocs fonctionnels renseignés à la fois. Tout message ne respectant pas cette règle se verra rejeté. Il y a 5 blocs fonctionnels différents :
- Unité de manutention : Identifié par : conteneur uniquement.
- BL : Identifié par sa référence.
- Booking : Identifié par sa référence.
- Marchandise : Identifié par son identifiant Ci5.
- Dossier : Identifié par sa référence.
3.9. Groupe fonctionnel « Evénements déclencheurs »
3.9.1. Élément
Groupe Fonctionnel : Evénements - Elément : 1/1 - Elément parent : tracing - Cardinalité : 1..N
Syntaxe Minimale :
xml
- Identifiant PCS de l’événement déclencheur — Statut :
o ; Format : AN..20 ; Marqueur : code ; Règles et conditions : Voir tableau ci-dessous - Indicateur import — Statut :
c ; Format : AN..1 ; Marqueur : import ; Règles et conditions : Voir tableau ci-dessous ; Valeur : Y=Oui, N=Non - Indicateur export — Statut :
c ; Format : AN..1 ; Marqueur : export ; Règles et conditions : Voir tableau ci-dessous ; Valeur : Y=Oui, N=Non
Objet de l’élément
L’élément « evenement-tracing » indique les différents types d’événements qui seront déclencheurs d’une notification sur l’entité spécifiée par l’élément « reference-tracing ».
Règles
L’élément « evenement-tracing » doit être présent au moins une fois dans le message.
Le tableau ci-dessous reprend les différentes valeurs des codes disponibles, ainsi que les indicateurs associés : toute combinaison ne vérifiant pas ce tableau pourra causer le rejet du message.
- AMQVA — Libellé Ci5 English (FR) : Pre arrival notification (notification de préarrivée) ; Explication : notification envoyée lorsqu'un cargo est publié (notification de préarrivée) pendant la période de surveillance choisie ; Indicateur IMPORT à "Y" possible : NON ; Indicateur EXPORT à "Y" possible : OUI
- ANDCBK — Libellé Ci5 English (FR) : Booking ; Explication : notification envoyée lorsque le cargo sur lequel porte la demande de Tracing est créé sur un Booking pendant la période de surveillance choisie ; Indicateur IMPORT à "Y" possible : NON ; Indicateur EXPORT à "Y" possible : OUI
- APD — Libellé Ci5 English (FR) : Manifest (manifeste) ; Explication : Notification envoyée lorsque le cargo du manifeste est publié pendant la période de surveillance choisie ; Indicateur IMPORT à "Y" possible : OUI ; Indicateur EXPORT à "Y" possible : NON
- ARRNAV — Libellé Ci5 English (FR) : Vessel arrival (arrivée navire) ; Explication : notification envoyée lorsque la RTA d'un Call est saisie ou mise à jour ET que la RTD n'est pas saisie. ; Indicateur IMPORT à "Y" possible : OUI ; Indicateur EXPORT à "Y" possible : NON
- BAD — Libellé Ci5 English (FR) : Release order (bon à délivrer) ; Explication : notification envoyée lorsqu'un Release Order est publié pour le cargo du tracing pendant la période de surveillance choisie ; Indicateur IMPORT à "Y" possible : OUI ; Indicateur EXPORT à "Y" possible : NON
- BAED — Libellé Ci5 English (FR) : Customs release (Relâche douane) ; Explication : notification envoyée lorsque le cargo du tracing obtient la Customs Release pendant la période de surveillance choisie ; Indicateur IMPORT à "Y" possible : OUI ; Indicateur EXPORT à "Y" possible : OUI
- BASE — Libellé Ci5 English (FR) : Final release (relâche finale) ; Explication : notification envoyée lorsque le cargo du tracing obtient la Final Release pendant la période de surveillance choisie ; Indicateur IMPORT à "Y" possible : NON ; Indicateur EXPORT à "Y" possible : OUI
- BASI — Libellé Ci5 English (FR) : Final release (relâche finale) ; Explication : notification envoyée lorsque le cargo du tracing obtient la Final Release pendant la période de surveillance choisie ; Indicateur IMPORT à "Y" possible : OUI ; Indicateur EXPORT à "Y" possible : NON
- DEPNAV — Libellé Ci5 English (FR) : Vessel departure (départ navire) ; Explication : notification envoyée lorsque la RTD d'un Call est saisie ou mise à jour. ; Indicateur IMPORT à "Y" possible : OUI ; Indicateur EXPORT à "Y" possible : OUI
- ENLEVEMENT — Libellé Ci5 English (FR) : Gate-Out (enlèvement) ; Explication : notification envoyée lorsqu'un Movement Report Gate-out (constat d'enlèvement) est effectué pour le cargo du tracing pendant la période de surveillance choisie ; Indicateur IMPORT à "Y" possible : OUI ; Indicateur EXPORT à "Y" possible : OUI
- RECU — Libellé Ci5 English (FR) : Gate-In (réception) ; Explication : notification envoyée lorsqu'un Movement Report Gate-in (constat de réception) est effectué pour le cargo du tracing pendant la période de surveillance choisie ; Indicateur IMPORT à "Y" possible : OUI ; Indicateur EXPORT à "Y" possible : OUI
- SORTIEUE — Libellé Ci5 English (FR) : Export Confirmation (confirmation d'export) ; Explication : notification envoyée lors de la réception du statut "Sortie effective" dans le message NETAT/RIE618 ; Indicateur IMPORT à "Y" possible : NON ; Indicateur EXPORT à "Y" possible : OUI
- TRANSB — Libellé Ci5 English (FR) : Transhipment (transbordement) ; Explication : notification envoyée lorsqu'un transbordement (Transhipment) est publié sur le cargo de la demande de Tracing pendant la période de surveillance choisie ; Indicateur IMPORT à "Y" possible : OUI ; Indicateur EXPORT à "Y" possible : NON
- TRANSF — Libellé Ci5 English (FR) : Transfer (transfert) ; Explication : notification envoyée lorsqu'un déplacement est effectué sur le cargo de la demande de Tracing pendant la période de surveillance choisie ; Indicateur IMPORT à "Y" possible : OUI ; Indicateur EXPORT à "Y" possible : OUI
- VAB — Libellé Ci5 English (FR) : Load (chargement) ; Explication : notification envoyée lorsqu'un Movement Report Load (constat de chargement) est effectué pour le cargo du tracing pendant la période de surveillance choisie ; Indicateur IMPORT à "Y" possible : NON ; Indicateur EXPORT à "Y" possible : OUI
- ???? — Libellé Ci5 English (FR) : Discharge (déchargement) ; Explication : notification envoyée lorsqu'un Movement Report Discharge (constat de déchargement) est effectué pour le cargo du tracing pendant la période de surveillance choisie ; Indicateur IMPORT à "Y" possible : OUI ; Indicateur EXPORT à "Y" possible : NON
- ???? — Libellé Ci5 English (FR) : Customs declared (déclaration en douane) ; Explication : notification envoyée lors de l'intégration d'une déclaration de douane AED Clearance sur le cargo du Tracing pendant la période de surveillance choisie ; Indicateur IMPORT à "Y" possible : OUI ; Indicateur EXPORT à "Y" possible : OUI
- ???? — Libellé Ci5 English (FR) : Empty gate-in (Retour du vide) ; Explication : notification envoyée lors de la création/intégration d’un MR Empty gate in sur un cargo, si l’add-on “empty depot” est activé ; Indicateur IMPORT à "Y" possible : OUI ; Indicateur EXPORT à "Y" possible : NON
3.9. Groupe fonctionnel « commentaires »
3.9.1. Élément
Groupe Fonctionnel : Commentaires - Elément : 1/1 - Elément parent : tracing - Cardinalité : 0..1
Syntaxe Minimale :
xml
- Identifiant PCS de l’événement déclencheur — Statut :
o ; Format : AN..20 ; Marqueur : code ; Règles et conditions : Voir tableau ci-dessous - Indicateur import — Statut :
c ; Format : AN..1 ; Marqueur : import ; Règles et conditions : Voir tableau ci-dessous ; Valeur : Y=Oui, N=Non - Indicateur export — Statut :
c ; Format : AN..1 ; Marqueur : export ; Règles et conditions : Voir tableau ci-dessous ; Valeur : Y=Oui, N=Non
Objet de l’élément
L’élément « commentaire-tracing » permet de fournir des commentaires littéraux sur le tracing à intégrer.
Règles
L’élément « commentaire-tracing » est présent zéro ou une fois dans l’élément « tracing ».
4. Exemples de messages de tracing
4.1. Exemple de message restreint
Le message restreint comprend le nombre minimal d’éléments et d’attributs requis pour intégrer un tracing dans le S.I.C.
```xml
4.2. Exemple de message complet
Le message complet comprend l’ensemble des éléments et attributs possibles pour intégrer un tracing dans le S.I.C.
```xml
Autre exemple de message (à télécharger au format xml) :
5. Acquittement fonctionnel
A chaque message reçu, le PCS renvoie un message d’acquittement fonctionnel afin de faire état du statut de l’intégration. Chaque partenaire émetteur peut s’abonner à un service et recevoir les messages d’acquittement fonctionnel du PCS.
5.1. Présentation du message
Le message d’acquittement fonctionnel a pour objectif d’informer le partenaire du résultat de l’intégration du message qu’il a envoyé. Ce résultat peut être de deux natures :
-
Acquittement fonctionnel positif :
- L’intégration du tracing a été réalisée,
- Le message d’acquittement fonctionnel est envoyé avec le statut validé (V),
- Le PCS envoie l’identifiant, le statut et la date du tracing créé dans le PCS.
-
Acquittement fonctionnel négatif :
- L’intégration du tracing n’a pu aboutir,
- Le message d’acquittement fonctionnel est envoyé avec le statut rejeté (R),
- Le PCS envoie la référence du tracing associée à la description de l’erreur survenue lors du processus d’intégration.
Un guide d’implémentation du message d’acquittement fonctionnel est disponible. Il contient une description détaillée du message.
A titre d’exemple, des messages d’acquittement fonctionnel positif et négatif lié au tracing sont fournis. Chaque message est accompagné de commentaires.
5.2. Message d’acquittement fonctionnel positif
5.2.1. Exemple de message d’acquittement fonctionnel positif
```xml
5.2.2. Commentaires
Le message d’acquittement fonctionnel ci-dessus fait référence au message de création de tracing fourni en exemple. Il reprend les caractères génériques des messages avec les groupes fonctionnels « entête message » et « entête document ».
Le marqueur
TRC) ayant pour référence la valeur «
TRACING01» a bien été intégré dans le PCS.
Le marqueur
TRACING01) et en lui associant un identifiant Ci5 (
170415775), créé le jj/mm/aaaa à hh :mn :ss avec le statut « V » (valide).
5.3. Message d’acquittement fonctionnel négatif
5.3.1. Exemple de message d’acquittement fonctionnel négatif
```xml
5.3.2. Commentaires
Le message d’acquittement fonctionnel ci-dessus fait référence au message de création de tracing fourni en exemple. Il reprend les caractères génériques des messages avec les groupes fonctionnels « entête message » et « entête document ».
Le marqueur
R » signifie que le tracing (
TRC) ayant pour référence la valeur «
TRACING01» n’a pu être intégré dans le PCS.
Le marqueur
TRACING01) et en lui associant une erreur permettant de motiver le rejet du tracing.
Lien des guides version PDF
Source : https://mgi-team.atlassian.net/wiki/spaces/DOCI5/pages/3240889268