Présentation

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

Définition et génération

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.

Description du flux XML produit

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)

Programmes wrapper

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.

Objets

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

Sous-programmes

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.

Debugger

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.

Informations retournées

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.

 

Paramétrage

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.

Serveur de Web services

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.

Testeur de Web services

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.

Description des classes clientes

 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
Positonnement du curseur – bloc^champ^indice

 

 

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 (Query)

 

 

 

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

Classe sous programme 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

 

 

 

 

 

Flux XML échangés

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.
Les fils sont des nœuds FLD

Attributs obligatoires :
ID 
: identifiant - obligatoire

<TAB>

Bloc de type tableau ou groupe de paramètres de dim >1.
Les fils sont des nœuds LIN

Attributs obligatoires :
ID 
: identifiant

Attributs en retour X3 :
DIM
: nombre de lignes

<LIN>

Ligne d’un bloc tableau ou d’une liste gauche ou d’un paramètre tableau

Attributs obligatoires :
NUM
: N° de ligne

Attributs en saisie/retour X3 :
ID 
: identifiant si non rattachée à un groupe tableau

<FLD>

Paramètre/Champ.
La valeur du champ est passée dans un nœud XML de type Text

Attributs obligatoires :
NAME
 : Nom du champ

Attributs en retour X3:
TYPE 
: Type du champ défini dans X3

Attributs facultatifs en retour X3:
FORMAT
 : Format du champ

MENULOCAL 
: Code du menu local
MENULAB : libellé du menu local dans la langue d’affichage(soap ctx)

MIMETYPE : Type mime pour les champs de type blob
ENCODING : Type d’encodage our les champs de type blob (Base64)
BYTES: Taille en octets our 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.
Les fils sont des nœuds de type ITM

Attributs obligatoires :
NAME
 : Nom du champ
 

<ITM>

Valeur du champ liste

Attributs idem tag <FLD>

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>

Paramètre des listes gauches

Exemple pour une liste gauche de SOH

Champ          colonne        

SOHNUM      1
ORDDAT      3
BPCORD      2
ORDSTA      5

Paramètre en entrée

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>

Paramètre des sous-programmes

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

Paramètre en entrée

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>