Toute fonction de type « objet Adonix » et« sous-programme » développée avec la plate-forme technologiqueAdonix peut être publiée sous forme de Web service.
Cette publication va construire un programme wrapper et une structure XMLdéfinissant les données à publier qui seront ensuite exploitées par leserveur de Web services.
Si tout élément correspondant aux critères techniques mentionnés (objet etsous-programmes) est publiable, Adonix fournit une liste d’objets et defonctions certifiées. Les autres objets pourront être générés, mais leurfonctionnement peut nécessiter de la mise au point (au même titre qu’unimport), spécialement pour les actions de mise à jour. Il est à noter que lespersonnalisations éventuelles sur les objets sont prises en compte dans laprocédure de génération, et demandent également à être testées de manièrespécifique.
Le serveur de Web services est installé sur une plate-forme.Net (enversion 14x) et est installé et administré par la console de configuration.
Il est nécessaire de définir un ensemble de pools de connexion vers lesdifférents dossiers Adonix que l’on souhaite publier.
Chaque Web service publié est conforme aux standards du marché (Soap etWSDL) et peut être appelé à partir de toute application tierce permettant del’instancier.
Ce document a pour objectifs de :
- Définir leséléments Adonix publiables sous forme de Web services
- Détailler laprocédure à suivre pour les publier
- Définir lesinterfaces de publication disponibles pour chaque type d’objet
Tout objet développé en technologie Adonix et tout élément décrit dans ledictionnaire des sous-programmes est éligible pour être généré sous forme deWeb service.
Cette éligibilité ne garantit pas le fonctionnement, qui va dépendre desrègles de développement observées. Le mode Web service est un mode de fonctionnementsans état, qui s’exécute a-interface, et qui ne tolère pas de ce fait,d’interruption ouvrant une nouvelle fenêtre en cours de traitement (àrapprocher d’un mode import).
Il est à noter que le choix technologique réalisé sur la plate-forme Adonixest de réutiliser le même code quelle que soit l’interface (C/S, Web ou Webservice), ce qui permet une réutilisabilité maximum et garantit la cohérencede la base (puisque ce sont toujours les mêmes contrôles qui serontexécutés).
La fonction de déclaration des sous-programmespermet de préciser les sous-programmes qui sont publiables en mode Web (caseà cocher Web services) et de les publier via la fonction de génération des Web services.
Cette fonction permet également de publier les objets.
Le programme de publication crée :
- une structure XMLde nom « Nom de publication ».xml qui est stockée dans lerépertoire X3_PUB/ « Nom du dossier »/GEN/ALL/WEBS
- un programmewrapper de nom WJ »Nom d’objet » « nom de variante »pour les objets sans publication des champs invisibles
- WJ »Nomd’objet » « nom de variante »_I pour les objetsavec publication des champs invisibles
- WR « Nomde publication » pour les sous-programmes
Avec chaque programme wrapper un programme de test automatique est crée quipermet d’appeler un sous-programme publié et d’appeler un objet par une desquatre méthodes proposées (lecture, création, modification, suppression) etpar la méthode liste.
Les éléments générés sont horodatés et un contrôle est effectué par leserveur de Web services avant tout appel à un programme wrapper pours’assurer que la version publiée et utilisée est bien la plus à jour.
Le fichier XML produit est écrit en codage UTF8 et est divisé encollections.
L’entête du document est décrite dans le nœud ADXDOC. Ses propriétés sontles suivantes :
- PNA : Nom depublication de l’élément
- NAM : Nom dela fenêtre associée à l’élément (pour les objets)
- TIM :Horodatage de génération
- OBJ : Nom del’objet généré (pour les objets seulement)
- TRA : Nom dela transaction choisie (si une transaction est choisie, objet seulement)
- INV : 1 siles champs invisibles sont publiés (la propriété est absente sinon, pour lesobjets seulement)
- PRG : Nom duprogramme publié (pour les sous-programmes uniquement
- SPG : Nom dusous-programme publié (pour les sous-programmes uniquement
- FOL : Nom dudossier
- SOL : Nom dela solution Adonix
- WRP : Nom duprogramme wrapper
- USER :Utilisateur X3 ayant déclenché la génération
- VER : Versiondu générateur
Une description de tous les champs participant à l’échange est donnée décritedans le nœud ADXDATA. Les données sont organisées en groupe, un grouperassemblant les données d’un bloc pour les écran, et d’un ensemble deparamètres de même cardinalité (ou selon le regroupement effectué) pourles sous programmes. Les propriétés du nœud GRP qui décrit les groupes sontles suivantes :
- NAM : Nom dugroupe. Ce nom est donné dans la description des sous-programmes (Groupe depublication) et est généré automatiquement pour les blocs des écrans(« Abréviation de l’écran »_ « Numéro du bloc »)
- TYB : Type debloc (valeurs possibles : Table, List, Pict, Text, Hidden)
- DIM : donnela dimension maximale pour les blocs de type tableau ou de variablesoccursées.
Les fils des nœuds GRP sont des nœuds FLD dont les propriétés sont lessuivantes :
- NAM : Nom del’élément (issu du dictionnaire)
- TYP : type dechaque variable (valeurs possibles : Integer, Char, Blob, Clob, Date,Decimal)
- LEN :longueur pour les champs de type Char, Blob et Clob
- MOD : typed’utilisation (valeurs possibles : Input, Display, Hidden)
- MAN : soncaractère obligatoire (la propriété est absente sinon
- MEN : si letype de la donnée s’appuie sur un menu local Adonix le numéro du menu localest donné dans cette propriété. La description du menu local dans chacune deslangues du dossier est donnée dans la collection ADXMEN du fichier
- DIM : pourles champs dimensionnés dans les blocs listes, donne la dimension
- C_« Codelangue » : son intitulé dans les différentes langues du dossier
Les groupes de paramètres suivants ne sont générés que pour les objets.
Collection ADXKEY : Elle décrit les colonnes composant la listegauche de l’objet. Chaque colonne est identifiée dans un nœud FLD qui disposedes mêmes propriétés que dans la collection ADXDATA (à l’exception desattributs MOD, MAN et DIM inutiles dans ce contexte)
Collection ADXMEN : Elle donne une description des menus locaux référencésdans les divers champs de l’objet. Chaque menu local est identifié dans unnœud MNU qui porte la propriété NO qui donne le numéro de menu local. Chaqueentrée de menu est stockée dans un nœud VAL qui possède les propriétéssuivantes :
- IND : Numérod’entrée de menu
- C_ « Code langue » : Intitulé dans la langue
Collection ADXSER : Elle décrit les différentes méthodes disponiblesdans l’objet. Chacune est stockée dans un nœud MET. Dans la première versionseules les actions standards (1 à 5) sont disponibles. Les propriétés du nœudMET sont :
- ID : Code dubouton (les codes des 5 actions standards sont READ – Lire, CREATE – Créer,MODIFY – Modifier, DELETE – Supprimer, LIST – Liste), les autres codescorrespondent aux boutons modélisés dans la fenêtre ne donnant pas lieu àouverture d’une nouvelle fenêtre (ce cas n’étant pas géré par les Webservices)
- C_ « Code langue » : Intitulé de l’action
Collection ADXREAD : Elle décrit les colonnes composant la clé de la tableprincipale de l’objet. La propriété TAB donne le nom de la table concernée.Les nœuds fils de ADXREAD sont des FLD qui décrivent chaque composante de laclé (les propriétés sont les mêmes que pour les nœuds FLD dans la collectionADXKEY)
Les programmes wrapper sont appelés par le serveur de Web services dont lerôle est de sérialiser / désérialiser le flux soap de / vers les paramètresattendus.
Les paramètres sont normalisés en variables d’entête et flux de données.Les variables d’entête servent à contrôler les flux émis et reçus. Leurdescription est le suivante :
- WW_OK Integer Statut de retour1=OK , 0=KO
- WW_ZONE Character Zone de sortie en cas d’erreur
- WW_STAT Integer Nombre d’évènements
- WW_GRAVEInteger(1..50) Gravité de message (1= Info, 2=Warning, 3=Bloquant)
- WW_MESS Character(1..50) Texte dumessage
- WW_ACTION Character Code action (IDde l’action à exécuter)
- WW_IDENT Character Identifiant (Cle1~Cle2~Cle3 …) ou clé début ou critères de sélection rapidesi liste
- WW_NB Integer Nombre d’enregistrements à lire / retournés
- WW_HORDATChar Horodatage de l’élément
- WW_TAB Char Identificationtableau (réservé pour utilisation future)
- WW_PAR Char(1..10) Identifiant de ligne de tableau (réservé pour utilisation future)
- WW_TRACE Clob Trace retournée à l’application cliente et paramètre d’activation du debugger
Lors de l’appel d’un Web service, le serveur de Web service transmet auprogramme wrapper l’horodatage de sa structure locale. Le serveur X3 vérifiesi cet horodatage est conforme à celui stocké sur le serveur. Si oui ilrépond à la requête, si non il renvoie une erreur et le serveur de Webservice envoie une requête technique pour récupérer la dernière version.
La génération du programme wrapper est une des étapes de la génération duWeb service. A l’intérieur du programme wrapper on trouve un programme detest qui permet de valider le fonctionnement de l’objet ou du sous-programmeen mode Web service, en simulant une exécution.
Le nom des programmes wrapper est normalisé :
- Pour lesobjets : WJ « Nom de l’objet » « Nom de latransaction » (+ « _I » si les champs invisibles sontpubliés)
- Pour lessous-programmes : WR « Nom de publication dusous-programme »
Les programmes wrapper sont générés avec des programmes de tests quipermettent de vérifier le fonctionnement du Web service à l’intérieur duprogiciel, sans construire d’application cliente. Ces programmes de testssont
- Un test de listegauche (TEST_LISTE) qui permet de lire n enregistrements (n=10 par défaut) etde les afficher dans une trace. Il est également possible de positionner desfiltres en chargeant la variable WW_IDENT. Chaque valeur est séparée par untilde (~). Exemples :
1. WW_IDENT= « ~~>01/01/2006~DIS001~ » pour rechercher lescommandes de vente postérieure au 1 janvier 2006 et appartenant au clientDIS001
2. WW_IDENT= « ~~>01/01/2006~D*~ »pour rechercher les commandes pour ls clients dont le nom commence par D
-
-
- Un test d’objet(TEST) dans lequel il faut positionner l’action WW_ACTION et les paramètresdont l’action a besoin (variables à modifier, clé à renseigner dansWW_IDENT). Une étiquette Goto DETAILRES (mise par défaut en commentaire)permet d’afficher dans une trace les informations retournées (avec la limited’une ligne par tableau)
- Un test desous-programme directement en tête du wrapper qui simule l’appel et quiexécute deux étiquettes (optionnelles) dans le sous-programme : INITWSavant l’appel et RESULTWS après l’exécution, ce qui permet au développeur decharger un contexte de test et d’écrire dans la trace les résultats dans sonsous-programme.
Quelques particularités des web services objets.
Ecrans complémentaires
Il est possible d’associer à des objets des objets des écranscomplémentaires qui sont à renseigner dans l’onglet environnement de l’objet.Ces écrans seront transmis à l’application cliente et les données retournéesdans les variables correspondant à ces masques, seront chargées dans cesmasques en simulant une saisie et donc en effectuant les contrôles définisdans les écrans. Les programmes liés à la fonction ont la responsabilité decharger ces masques à l’ouverture de la fonction et de mettre à jour lestables concernées, si ce n’est pas fait dans l’objet.
Contrôle de mise à jour
Si la table principale de l’objet comporte les colonnes UPDDAT, UPDTIM etUPDUSR, ces informations sont retournées dans le flux XML de réponse lorsd’une lecture dans le groupe ADXTEC dans deux nœuds de type FLD
- WW_MODSTAMP :donne l’horodatage de la dernière modification sous la forme SSAAMMJJHHMMSS(concaténation de UPDDAT et UPDTIM)
- WW_MODUSER :donne le code utilisateur X3 du dernier modificateur
Si ces informations sont retournées au serveur dans un flux de mise à jour(modification ou suppression), ces valeurs sont comparées à celles présentesau moment de l’exécution dans le fichier principal de l’objet. Sil’horodatage remonté est inférieur à celui de l’enregistrement de la table,c’est que l’enregistrement a été modifié entre la lecture et l’ordre de miseà jour. Cette dernière est alors refusée avec un message explicite indiquantque l’enregistrement a été modifié depuis la dernière lecture. Cettefonctionnalité n’est activée que si les valeurs sont remontées dans le flux.
Ecrans liste-détail
C’est par exemple le cas des écrans adresse. Un tableau contient en champsinvisibles l’ensemble des informations qui sont visualisées en détail dans unbloc liste associé. Ce type de fonctionnement est normalement prévu pourfonctionner de manière interactive, l’utilisateur choisissant la ligne surlaquelle il souhaite travailler. En mode Web services, toutes lesinformations du tableau seront exportées et la saisie ligne à ligne serasimulée. Tous les contrôles associés au bloc liste seront ainsi exécutés,garantissant de fait l’intégrité des données.
La modélisation de ce type de bloc demande quelques précisions. Au niveaudu dictionnaire des écrans, il faut que :
- le bloc listedétail soit associé au bloc tableau (colonne bloc tableau)
- les noms des champsdu bloc liste doivent se déduire des noms des champs invisibles du bloctableau par une formule du type « Nom du champ blocliste »=constante + « nom du champ bloc tableau »
- le dernier champinvisible et de type C (entier) du bloc détail est considéré comme lavariable de contrôle du numéro de ligne dans le tableau et est initialisé entant que tel par le programme wrapper lors de l’appel de chaque ligne.
Deux précautions à prendre
- les actions dubloc tableau ne sont pas exécutées. Il faut donc veiller à ne mettre aucuneaction indispensable dans ce contexte.
- En cas demodification, il faut passer dans le flux XML le nombre de lignes total dutableau, une fois la modification effectuée, faute de quoi on se retrouvera avecun nombre de lignes égal au plus grand numéro de ligne modifié.
Les Web services associés aux sous-programmes fonctionnent de manière trèssimple dans la logique de la plate-forme de développement. Il suffit decaractériser ces sous-programmes dans l’objet de gestion des sous-programmes,de définir les groupes de publication et de publier le Web service. La seuleparticularité concerne la possibilité de gérer jusqu’à 50 messages au lieud’un seul en fonctionnement normal. Il suffit pour cela d’utiliser les appelsstandards
- CallMESSAGE(MESSAGE) from GESECRAN pour un message d’information
- CallAVERTIR(MESSAGE,2) from GESECRAN pour un message d’avertissement
- CallERREUR(MESSAGE) from GESECRAN pour un message d’erreur
Les messages sont ainsi ajoutés à la table standard des messages des Webservices.
Il est possible d’activer le debugger X3 intégré à l’application (version Web)à partir des Web services. Cela se fait directement en utilisant le testeurde Web services livré avec le serveur Web, sinon, il suffit de charger dansle flux XML renvoyé au serveur de Web service le champ clob WW_TRACE avecl’information :
adonix.debug.on=on;adonix.debug.host=@IP du poste ou doit s’exécuter ledebugger ;adonix.debug.port=port utilisé par le debugger (1789habituellement)
Il faut bien sur au préalable lancer l’application Java de debugging.
Dans le flux d’informations retournées par le serveur de Web services,outre les données applicatives, et les données d’entête qui précisent lestatut global, le nombre de messages et pour chacun le texte et leniveau de gravité associé, des informations permettent de détailler lamanière dont le Web service a répondu. En voici la liste :
- status=[1] Statut Global 1 (OK) , 0 (erreur)
- hasResult=[true] True si desrésultats ont été rendus par le Web service
- hasProcessReport=[true] Y-a-t-il eu un rapport d’exécution
hasTraceRequest=[true] Y-a-t-il eu unetrace X3 rendue (selon paramètre du contexte d’appel)
clientDuration=[322,88] Temps de réponse client (en millisecondes)
serverDuration=[171,01] Temps deréponse serveur Web (inclus serveur X3)
loadWebsDuration=[0,1] Tempsd’attente pour charger la description XML du web service
poolDistribDuration=[0,15] Tempsd’inscription dans la liste d’attente
poolWaitDuration=[30,6] Temps d’attentepour trouver une session disponible pour exécuter
poolExecDuration=[124,17] Tempsd’exécution dans le serveur Adonix
poolRequestDuration=[154,93] Temps total d’exécution de la requêtedans le pool
switchUser=[false] Y-a-t-il eu un changementd’utilisateur X3 dans la session utilisée par le pool
switchLang=[false] Y-a-t-il eu un changement delangue dans la session utilisée par le pool
flushAdx=[false] Y-a-t-il eu un rechargement des adx dans la session utilisée par le pool
reloadWebs=[false] Y-a-t-il eu un rechargementdescription XML dans la session utilisée par le pool
poolEntryIdx=[0] Indice dela session utilisée dans le groupe
rowInDistribStack=[1]Rang d’inscription dans la file d’attente du pool
nbMessage=[0] Nombre demessages renvoyés par l’application
C’est à partir de l’analyse de ces informations qu’il sera possible devalider la pertinence de la taille du pool de connexions, et si les tempsd’attente au niveau du pool (poolWaitDuration) deviennent élevés de rajouterdes entrées pour assurer une meilleure fluidité des requêtes.
Le paramétrage des pools de connexion s’effectue avec la console deconfiguration. Les informations nécessaires à définir pour chaque poolseront :
- la définition d’unalias qui permettra d’adresser le pool
- la définition d’identifiants permettant de se connecter à l’application
- le choix d’unelangue de connexion par défaut
- la définition dela taille du pool (en accord avec le nombre de licences autorisées)
Il est possible de définir plusieurs pool pour un dossier, et ainsi de lesspécialiser par fonction par exemple.
Une fois la configuration définie, le serveur de Web services ouvre lesconnexions qui lui sont nécessaires sur le dossier ainsi paramétré.
Dans les paramètres avancés, il est possible de mettre en place destraces, très utiles en cas de problème de fonctionnement.
Sur le serveur Web, l’onglet « serveur de Web services »accessible dans les pages d’administration, permet de visualiser l’ensembledes pools définis et leur état (démarré ou arrêté).
Il permet également d’arrêter et de relancer des pools de connexion, devisualiser les paramètres des pools, mais la modification des paramètres despools se fait exclusivement avec la console de configuration.
Une trace d’activité du serveur permet de visualiser tous les arrêts etdémarrages des entrées des pools.
Le gestionnaire de pool a la charge de répartir les requêtes dans lesentrées disponibles, en choisissant l’entrée disponible la plus« proche » de la demande (même utilisateur, même langue), et desérialiser les demandes si il n’y a pas d’entrée disponible.
L’application « testeur de Web services » est livrée avec leserveur Web et permet très simplement de vérifier le fonctionnement completde la chaîne des Web services.
Cette application propose 4 onglets :
- La définition desparamètres d’accès (choix du pool, informations de connexion, utilisation dela trace et du debugger)
- L’utilisation duWeb service sous-programme avec la possibilité de saisir le flux XML àenvoyer au serveur de traitement dans une zone éditable.
- L’utilisation duWeb service liste d’objet, avec la possibilité de définir le nombred’enregistrement à retourner et des filtres sur les colonnes
- L’utilisation duWeb service objet, avec toutes ses méthodes (Lire, créer, modifier,supprimer, action) et la possibilité de saisir le flux XML à renvoyer auserveur de traitement dans une zone éditable, et la possibilité de saisirjusqu’à 5 composantes de clé pour les actions de lecture et de modification
Le flux XML à envoyer au serveur est parsé localement et les erreurs sontsignalées.
Un rapport d’analyse des paramètres envoyés et reçus permet de valider lefonctionnement technique.
La réponse XML renvoyée par le serveur de traitement est affichée dans unezone d’édition.
Pour chacun de ces Web services, il et aussi possible d’interroger leserveur pour récupérer et afficher la description XML des paramètres généréessur le serveur de traitement.
Liste des classes web services
Description des classes de base
Namespace : com.adonix.webservices.stub
Classe CAdxCallingContext | Contexte d’appel du sous-programme - Soap Header | ||
| Properties |
| |
|
| public string codeLang | Code langue pour l’affichage – Pool de connexion |
|
| public string codeUser | Utilisateur X3 – Pool de connexion |
|
| public string password | Mot de passe – Pool de connexion |
|
| public string poolAlias | Alias du pool de connexion |
Classe CAdxMessage | Message renvoyé par X3 | ||
| Properties |
| |
|
| public string type | Type de message - 1= Info - 2=Warning - 3=Bloquant |
|
| public string message | Libellé du message dans la langue d’affichage |
Classe CAdxResultXml | Résultat de l’appel d’un sous programme X3 | ||
| Properties |
| |
|
| public int status | 1=OK – 0=KO |
|
| public string zone | Zone d’erreur – Objets uniquement |
|
| public CAdxMessage[] messages | Liste des messages |
|
| public string resultXml | Donnés renvoyée au format xml |
|
| Public double timeServer | Temps de traitement sur le serveur en ms |
|
| Public double timeX3Call | Temps pour l’exécution du sous-programme X3 |
|
| Public double timeLocal | Temps de traitement sur le serveur de webservice (timeServer- timeLocal) |
|
| Public String zone | Zone d’erreur |
Classe CAdxParamKeyValue | Clé/Valeur - Clé d’un identifiant d’un objet X3 | ||
| Properties |
| |
|
| public string key | Nom du champ X3 |
|
| public string value | Valeur - Cette String doit être compatible avec le type du champ(Ex : yyyymmdd pour les dates) |
Les champs qui composent la clé pour accéder à l’objet sont disponibles dansle xml généré par X3
Classe objet X3.
Nom de la classe (proxy et serveur) : ‘CAdxObjectXML’
La description XML de l’objet est disponible dans le fichier généré parX3 :
Classe CAdxObjectXml |
| ||
| Properties |
| |
|
| public CAdxCallingContext headerCtx | Contexte d’appel du sous-programme |
| Methods |
| |
|
| public CAdxObjectXml () | Constructeur |
|
| Public CAdxResultXml save ( String publicName, string objectXml) | Sauvegarde de l’objet publicName est le code de publication de l’objet X3 objectXml contient les données xml de l’objet Renvoie l’objet sauvegardé si OK |
|
| Public CAdxResultXml read ( String publicName, CAdxParamKeyValue [] objectKeys) | Lecture de l’objet publicName est le code de publication de l’objet X3 objectKeys contient l’identifiant Renvoie l’objet si OK |
|
| Public CAdxResultXml delete ( String publicName, CAdxParamKeyValue [] objectKeys) | Suppression de l’objet publicName est le code de publication de l’objet X3 objectKeys contient l’identifiant Ne renvoie pas de données X3 – result est vide |
|
| Public CAdxResultXml modify ( String publicName, CAdxParamKeyValue [] objectKeys, String objectXml) | Modification de l’objet identifié par objectKeys publicName est le code de publication de l’objet X3 objectKeys contient l’identifiant objectXml contient les données à modifier (structure de l’objet) Renvoie l’objet modifié si OK |
|
| Public CAdxResultXml action( String publicName, String aCodeAction, String objectXml) | Autre action sur l’objet. Il s’agit des boutons qui restent sur la mêmefenêtre tout en modifiant l’affichage (valorisation de la commande,changement devise ..) publicName est le code de publication de l’objet X3 aCodeAction contient le code de l’action objectXml contient les données xml de l’objet Renvoie l’objet si OK |
Classe liste gauche de l’objet X3
| |
|
Nom de la classe : ‘CAdxObjectListXml’
Classe CAdxObjectListXml |
| ||
| Properties |
| |
|
| public CAdxCallingContext headerCtx | Contexte d’appel du sous-programme |
| Methods |
| |
|
| public CAdxObjectListXml () | Constructeur |
|
| Public CAdxResultXml query ( String publicName, CAdxParamKeyValue [] objectKeys) | Lecture de la liste des objets publicName est le code de publication de l’objet X3 objectKeys contient les critères de sélection + caractères spéciauxutilisés pour la sélection) Renvoie le résultat dans CAdxResultXml.result |
Les champs qui composent la liste gauche sont disponibles dans le xmlgénéré par X3
| |
Nom de la classe : ‘CAdxSubProgramXml’
Classe CAdxSubProgramXml’ |
| ||
Properties |
| ||
| public CAdxCallingContext headerCtx | Contexte d’appel du sous-programme | |
Methods |
| ||
| public CAdxSubProgramXml () | Constructeur | |
| Public CAdxResultXml runXml ( String publicName, String aInputXml) | Exécution du sous programme publicName est le code de publication du sous-programme X3 aInputParamsXml contient les paramètres XML en entrée Renvoie le résultat dans CAdxResultXml.result | |
|
|
|
|
Les échanges entre l’application cliente et le serveur de Web services sefont en XML.
Un WSDL unique est crée pour tous les Web services Adonix comprenant tous leschamps de l’entête et un paramètre unique de type string contenant la partievariable.
Description du flux montant (application cliente -> serveur)
Tag | Description |
<PARAM> | Nœud racine d’un paramètre webservice XML Aucun attribut |
<RESULT> | Nœud racine d’un résultat de l’appel d’un webservice XML Aucun attribut |
<GRP>
| Bloc de type liste ou groupe de paramètres de dim =1. Attributs obligatoires : |
<TAB> | Bloc de type tableau ou groupe de paramètres de dim >1. Attributs obligatoires : Attributs en retour X3 : |
<LIN> | Ligne d’un bloc tableau ou d’une liste gauche ou d’un paramètre tableau Attributs obligatoires : Attributs en saisie/retour X3 : |
<FLD> | Paramètre/Champ. Attributs obligatoires : Attributs en retour X3: Attributs facultatifs en retour X3: MIMETYPE : Type mime pour les champs de type blob LENGTH : Nombre de caractères pour les de type clob |
<LST> | Champ liste (multi-valué) uniquement dans les objets X3. Attributs obligatoires : |
<ITM> | Valeur du champ liste |
Paramètres des sous-programmes objet
Paramètre en entréepour les liste gauches
Il n’est pas obligatoire de rattacher les champs FLD des listes à un nœudde type LST.
Ils peuvent être directement rattachés au nœud racine PARAM
Si le champ n’est pas unique dans la fenêtre, c’est le premier paramètretrouvé (pour l’appel du sous-programme) qui sera pris en compte. Ce choix estde la responsabilité du programmeur
Paramètre en entrée pour les tableaux
Les lignes des tableaux LIN ne sont pas obligatoirement rattachées à unnœud de type TAB.
Elles peuvent comporter un ID qui est l’ID du bloc tableau.
Il est obligatoire de rattacher les champs FLD des lignes des tableaux àun nœud de type LIN
Exemple de structure XML pour passer une commande (SOH).
Dans les exemples ci-dessous les paramètres en gris sont facultatifs.
<PARAM>
<GRP ID="SOH0_1">
<FLDNAME="BPCORD">DIS001</FLD>
<FLDNAME="CUSORDREF">XXXXXX</FLD>
<FLDNAME="SOHTYP">WEB</FLD>
<FLDNAME="SALFCY">ASN</FLD>
</GRP>
<GRP ID="SOH1_1">
<FLDNAME="BPAADD">C01</FLD>
</GRP>
<GRP ID="SOH2_1">
<FLDNAME="STOFCY">ASN</FLD>
</GRP>
<TAB ID="SOH4_1">
<LIN ID= "SOH4_1"NUM="1">
<FLDNAME="ITMREF">CUB100</FLD>
<FLDNAME="QTY">50</FLD>
<FLDNAME="WALLQTY">50</FLD>
</LIN>
<LIN ID="SOH4_1"NUM="2">
<FLDNAME="ITMREF">CD100</FLD>
<FLDNAME="QTY">10</FLD>
<FLDNAME="WALLQTY">10</FLD>
</LIN>
<TAB>
</PARAM>
Données renvoyées - CAdxResultXml.result
Règles pour les listes
Les champs des listes sont obligatoirement attachés à un nœud de type LST
Règles pour les tableaux
Les lignes des tableaux LIN sont obligatoirement attachés à un nœud de typeTAB
Les champs des lignes des tableaux sont obligatoirement attachés à un nœudde type LIN
Exemple de structure XML renvoyée pour commande (SOH).
<?xml version="1.0" encoding="ISO-8859-1"standalone="yes" ?>
<RESULT>
<GRP ID="SOH0_1">
<FLDNAME="SOHNUM" TYPE="String"FORMAT=“XXXX“>>102314521</FLD>
<FLDNAME="BPCORD">DIS001</FLD>
<FLDNAME="BPCNAM">Galeries Lafayette</FLD>
<FLDNAME="CUSORDREF">XXXXXX</FLD>
<FLDNAME="SOHTYP">WEB</FLD>
<FLDNAME="SALFCY">ASN</FLD>
</GRP>
<GRP ID="SOH1_1">
<FLDNAME="BPAADD">C01</FLD>
…
</GRP>
<GRP ID="SOH1_2">
<FLDNAME="REP">REP01</FLD>
…
</GRP>
…
<TAB ID="SOH4_1"DIM="3">
<LINNUM="1">
<FLD NAME="ITMREF">CUB100</FLD>
<FLD NAME="QTY">50</FLD>
<FLD NAME="WALLQTY">50</FLD>
<FLD NAME="GROPRI">26.36</FLD>
</LIN>
<LINNUM="2">
<FLD NAME="ITMREF">CD100</FLD>
<FLD NAME="QTY">10</FLD>
<FLD NAME="WALLQTY">10</FLD>
<FLD NAME="GROPRI">5.57</FLD>
</LIN>
<LINNUM="3">
<FLD NAME="ITMREF">PUZ01</FLD>
<FLD NAME="QTY">100</FLD>
<FLD NAME="WALLQTY">100</FLD>
<FLD NAME="GROPRI">97.47</FLD>
</LINE>
</TAB>
…
<GRP ID="SOH4_4" X3CODE="SOH4_4">
<FLDNAME="ORDNOT">1025.64</FLD>
<FLDNAME="ORDATI">1245.17</FLD>
</GRP>
</RESULT>
Exemple pour une liste gauche de SOH
Champ colonne
SOHNUM 1
ORDDAT 3
BPCORD 2
ORDSTA 5
Le paramètre en entrée est un tableau de couples NomChamp/Valeur(CAdxParamKeyValue).
Le nom de champ est unique.
La classe serveur sait faire le lien entre le nom du champ et le N° de lacolonne via la description XML de la liste.
Exemple de paramètre XML
Liste des commandes ouvertes pour le client DIS001
<PARAM>
<FLDNAME="SOHNUM">DIS001</FLD>
<FLDNAME="ORDSTA">0</FLD>
</PARAM>
Données renvoyées - CAdxResultXml.result
<RESULT SIZE="2">
<LIN NUM="1">
<FLDNAME="SOHNUM">ABC154687</FLD>
<FLDNAME="ORDDAT">20040706</FLD>
<FLDNAME="BPCORD">DIS001</FLD>
<FLDNAME="ORDSTA" MENULAB="open"MENULOCAL="166"0</FLD>
</LIN>
<LIN NUM="2">
<FLDNAME="SOHNUM">ABC86943</FLD>
<FLDNAME="ORDDAT">20040516</FLD>
<FLDNAME="BPCORD">DIS001</FLD>
<FLDNAME="ORDSTA" MENULAB="open"MENULOCAL="166">0</FLD>
</LIN>
</RESULT>
Ex sous-programme
Calcul de prix et disponibilité - STOCKPRI
Param Type Dim Arg
BPCODE Char 1 Value Group 1 Codeclient
SALFCY Char 1 Value Group 1 Site de vente
STOFCY Char 1 Value Group 1 Site de stock
CUR Char 1 Value Group 1Devise
ITMREF Char 50 Value Group 2 Codes article
QTYREQ Char 50 Value Group 2 Quantités demandées
QTYAVAIL Char 50 Reference Group 2 Quantités disponibles
NETPRI Char 50 Reference Group 2 Prix hors taxes
Comme le nom du paramètre est unique, les paramètres de dimension 1 ou Nsont attachés au nœud PARAM.
Les lignes des tableaux doivent être créés dans l’ordre.
L’utilisateur ne se soucie pas de la structure des paramètres dessous-programmes au niveau d’X3.
Structure XML pour l’appel
Pas de rattachement des paramètres même pour les paramètres de dimension>1.
<PARAM>
<GRP ID=”GROUP1”> Facultatif
<FLD NAME="BPCODE">DIS001</FLD>
<FLDNAME="SALFCY">ASN</FLD>
<FLDNAME="STOFCY">ASN< /FLD>
<FLDNAME="CUR">USD</FLD>
</GRP>
<TAB ID=”GROUP2” NUM=”1”> Facultatif
<LINID=”GROUP2” NUM=”1”> Facultatif – Obligatoire si noeud TAB mais sans l’ID
<FLD NAME="ITMREF">CUB100</FLD>
<FLD NAME="QTYREQ">5</FLD>
</LIN>
<LINID=”GROUP2” NUM=”2”>
<FLD NAME="ITMREF">PUZ01</FLD>
<FLD NAME="QTYREQ">15</FLD>
</LIN>
<LINID=”GROUP2” NUM=”3”>
<FLD NAME="ITMREF">CD100</FLD>
<FLD NAME="QTYREQ">6</FLD>
</LIN>
</TAB>
</PARAM>
Données renvoyées - CAdxResultXml.result
Règle pour les paramètres de dimension1
Les champs sont rattachés sous les nœuds GRP
Règle pour les paramètres de dimension1
Les lignes LIN sont rattachées sous les nœuds TAB
Les champs FLD sont rattachés sous les nœuds LIN
Structure XML renvoyée
<RESULT>
<GRP ID=”GROUP1”>
<FLDNAME="BPCODE">DIS001</FLD>
<FLDNAME="SALFCY">ASN</FLD>
<FLDNAME="STOFCY">ASN</FLD>
<FLDNAME="CUR">USD</FLD>
</GRP>
<TAB ID=”GROUP2”>
<LINNUM=”1”>
<FLD NAME="ITMREF">CUB100</FLD>
<FLD NAME="QTYREQ">5</FLD>
<FLDNAME="QTYAVAIL">0</FLD>
<FLDNAME="NETPRI">78.44</FLD>
</LIN>
<LINNUM=”2”>
<FLD NAME="ITMREF">PUZ01</FLD>
<FLD NAME="QTYREQ">15</FLD>
<FLDNAME="QTYAVAIL">1</FLD>
<FLDNAME="NETPRI">27.81</FLD>
</LIN>
<LINNUM=”3”>
<FLD NAME="ITMREF">CD100</FLD>
<FLD NAME="QTYREQ">6</FLD>
<FLDNAME="QTYAVAIL">9</FLD>
<FLDNAME="NETPRI">94.85</FLD>
</LIN>
</TAB>
</RESULT>