S2B Training WS Level 1 Oma FR

Sage X3
Web Services
Niveau 1
Sage X3 Support to Business
10/08/2018
Bienvenue!
• Qui suis-je?
• Qui êtes-vous?
• Rappel des prérequis
• Emploi du temps, pauses et règles

Formation Web Services
Agenda
1. Qu’est-ce qu’un web service?
2. Comment invoquer les Web Services SOAP X3 depuis Mise en pratique 1 – Liste de clients
un portail web en PHP
3. Architecture des Web Services Sage X3 Mise en pratique 2 – Publication
4. Paramétrage des Web Services d’objets SOH
5. Publications et Tests Mise en pratique 3 – Execution du
6. Mise à jour du portail web PHP & Comment ajouter des Web Service YOSOH dans Soapui
produits
7. Bonnes pratiques & Performances
8. Limitations
9. Nouveaux Web Services X3 (REST)
10. Comment appeler des Web Services REST à partir d’X3
25/02/2019 3
Ce que vous allez
apprendre
• Une compréhension à 360° des
Web Services
• Comment paramétrer et tester les
Web Services
• Comment utiliser un web service
extérieur à Sage X3
• Être complètement autonome
dans l’implémentation d’un web
service.
25/02/2019 4
1 – Qu’est-ce qu’un Web
Service?
• Définition
• RESTful en Web Service
• SOAP
25/02/2019 5
Définition
Un web service est une collection de protocoles ouverts et de standards utilisés pour échanger des
données entre des applications ou des systèmes.
Des applications logicielles écrites dans divers langages de programmation et tournant sur diverses
plateformes peuvent utiliser des web services pour échanger des données à travers des réseaux
d’ordinateurs, comme internet, d’une manière similaire à la communication entre processus d’un
même ordinateur.
Les web services se fondent sur des protocoles autorisant la standardisation de l’échange.
Les web services X3 englobent différentes méthodes:
• Objet: exécution d’une tâche commerciale
• Sous-programmes: Exécuter du code
• Liste: Requérir des données
Les web services sont une tendance majeure pour la disponibilité web et mobile.
25/02/2019 6
Qu’est-ce qu’un web service RESTful?
Les principes suivants encouragent la technologie RESTful (simplicité, légèreté et rapidité des
applications):
• L’identification de ressources à travers un URI (Uniform Resource Identifier): un web service
RESTful expose un ensemble de ressources qui identifient les cibles de son interaction avec ses
clients. Ces ressources sont identifiées par des URIs, qui fournissent un espace d’adressage
global pour la recherche de ressources et de services.
• REST(REpresentational State Transfert) est un style architectural et un design pour les
architectures logicielles réseau.
• Les concepts REST sont désignés comme « ressources ». Une représentation de ressource doit
être stateless. Elle est représentée par un type de média, tel que XML, JSON, et RDF.
Les ressources sont manipulées par des composants. Les composants effectuent des requêtes et
manipulent les ressources via une interface standard uniforme. Dans le cas du HTTP, cette
interface consiste en des opérations standard: GET, PUT, POST, DELETE.
25/02/2019 7
Communication Client-Serveur
Les architectures client-serveur ont une séparation très distincte de préoccupations. Toutes les
applications conçues en style RESTful doivent également être client-serveur.
Stateless
Chaque requête client vers le serveur nécessite que son état soit totalement représenté. Le serveur
doit être capable de comprendre totalement la requête client sans utiliser le contexte serveur ni l’état
de la session serveur. Tout état doit donc être conservé côté client.
Stockable en mémoire cache

Des contraintes de cache peuvent être utilisées, permettant d’indiquer si les données de la réponse
sont ou non stockables en cache. Toute donnée stockable en cache peut être réutilisée comme
réponse à la même requête.
25/02/2019 8
Interface Uniforme
Tous les composants doivent interagir à travers une interface unique et uniforme. Comme toutes les
interactions entre composants interviennent via cette interface, l’interaction avec différents services
est très simple. L’interface est la même! Cela signifie également que les changements
d’implémentation peuvent être faits isolément. Ces changements n’affecteront pas les interactions
fondamentales entre composants car l’interface uniforme est toujours inchangée.
Un désavantage est que l’on est obligé d’utiliser l’interface. Si une optimisation pourrait être fournie à
un service spécifique en changeant l’interface, pas de chance: REST l’interdit. Malgré cela, REST est
optimisé pour le web, et bénéficie donc d’une grande popularité par rapport à HTTP.
Le concept présenté ci-dessus représente les caractéristiques essentielles de REST et différencie
l’architecture REST des autres architectures de web services. Il est nécessaire de noter qu’un service
REST est un web service, mais qu’un web services n’est pas forcément un service REST.
25/02/2019 9
Qu'est-ce que SOAP?
SOAP (Simple Object Access Protocol) est un protocole de communication qui permet à des
programmes tournant sur des systèmes d’exploitation différents (comme Windows et Linux) de
communiquer, en utilisant HTTP (Hypertext Transfer Protocol) et XML (eXtensible Markup Language).
25/02/2019 10
Qu'est-ce que SOAP?
Depuis que les protocoles Web sont installés et disponibles à l’utilisation par toutes les plateformes
majeures de systèmes d’exploitation, HTTP and XML fournissent une solution permettant à des
programmes qui tournent sur des systèmes d’exploitation différents dans un même réseau de
communiquer les uns avec les autres. SOAP spécifie exactement comment encoder une entête
HTTP et un fichier XML pour qu’un programme sur une machine donnée puisse appeler un autre
programme sur une autre machine et lui communiquer de l’information. SOAP spécifie également
comment le programme appelé peut retourner une réponse. Malgré son appariement fréquent avec
HTTP, SOAP accepte également d’autres protocoles de transport.
SOAP définit le format de message (fondé sur XML) utilisé par les applications de web services pour
communiquer et opérer les unes avec les autres à travers le Web. L’environnement hétérogène du
web exige que les applications acceptent un protocole commun d’encodage des données et de
format de messages. SOAP fournit un standard d’encodage XML pour les messages permettant
d’appeler des fonctions dans d’autres applications.
25/02/2019 11
Qu'est-ce que SOAP?
Le Web Services Description Language (WSDL) est un langage de définition d’interface fondé sur
XML et utilisé pour décrire la fonctionnalité offerte par un web service.
25/02/2019 12
REST vs SOAP
Différences entre SOAP et REST
• SOAP est un protocole. REST est un style architectural.
• SOAP est l’acronyme de Simple Object Access Protocol. REST est l’acronyme de REpresentational State Transfer.
• SOAP ne peut pas utiliser REST car SOAP est un protocole. REST peut utiliser les web services avec SOAP car
c’est un concept et qu’il peut donc utiliser tout protocole comme HTTP ou SOAP.
• SOAP utilise des interfaces de services pour exposer la logique commerciale. REST utilise des URIs.
• En Java, JAX-WS est l’API Java pour les web services SOAP, et JAX-RS est l’API Java pour les web services
RESTful.
• SOAP définit des standards devant être scrupuleusement suivis. REST ne définit pas de standards comme SOAP.
• SOAP nécessite plus de bande passante et de ressources que REST.
• SOAP définit sa propre sécurité. Les web services RESTful héritent des mesures de sécurité du moyen de
transport sous-jacent.
• SOAP permet uniquement le format XML. REST permet différents formats de données commme Plain text, HTML,
XML, JSON etc.
• REST est actuellement préféré à SOAP.
Les web services SOAP X3
Avec SAFE X3, vous pouvez publier des Objets, des Listes d’objets et des Sous-programmes à travers des
web services qui les rendront accessibles à des applications externes depuis internet :
• Un site web public commercial créant des commandes en X3
• Une application d’entreprise autre que X3
• Une application commerciale de vente sur un PDA (Personal Digital Assistant)
• …
Les liens habituels entre ces applications sont soumis aux contraintes suivantes:
• Le besoin d’accéder à X3 de manière totalement synchrone
• Sécurité maximale (pas de fichiers de données/texte en transit sur les serveurs)
X3 publie un unique web service qui donne accès à tous les objets et sous-programmes par trois différentes
méthodes.
février 19
Méthodes de web service X3
Trois Méthodes
X3 publie un unique Web Service contenant trois types de méthodes: Objets, Listes d’Objets et Sous-
programmes.
• Objets: pour créer, modifier ou supprimer un enregistrement d’objet X3; pour exécuter les boutons ou menus
liés à ces objets sous conditions:
- Commandes de vente
- Clients
- Produits
• Listes d’objets: Une méthode effectuant une requête sur la liste gauche de l’objet principal, i.e. fournissant
une liste des enregistrements au même format que le navigateur de gauche X3.
• Sous-programmes: Une méthode pour appeler un sous-programme X3 (code X3) déclarée dans le
dictionnaire des sous-programmes, par exemple:
- Obtenir une liste de prix pour une combinaison produit/client
- Obtenir une image de produit
- Obtenir le stock disponible pour un produit
- Allouer les réservations des clients
- (Tout sous-programme X3 ne nécessitant pas d’interaction utilisateur ou de fenêtre X3)
février 19
2 – Comment invoquer
les web services SOAP
X3 depuis un portail web
en PHP
• PHP et Syntaxe
• Appel d’un Web Service X3
• Eclipse PHP
25/02/2019 16
Contexte
Le portail PHP vous donne accès en temps réel à vos données Sage X3 (par exemple à vos
commandes). Vous n’avez pas besoin de partager des fichiers lourds par email ou sur un réseau.
Comme les données restent dans X3, et ne sont pas sauvegardées sur un serveur externe, cette
manière de procéder est plus sécurisée. Les employés mobiles (métiers vente par exemple) peuvent
non seulement visionner les données, mais également les modifier et créer de nouveaux
enregistrements (comme de nouvelles commandes) depuis n’importe quel ordinateur, pourvu qu’il soit
doté d’un accès internet via un navigateur.
Vous pouvez créer le portail en utilisant la fonctionnalité Sage X3 SOAP web services et
WampServer®, qui est un environnement Windows de développement web vous permettant de créer
des applications web avec Apache2, PHP, et une base de données MySQL. De plus, PhpMyAdmin
vous permet de gérer facilement vos bases de données [Source: wampserver.com].
février 19
Qu'est-ce que PHP?
PHP (PHP Hypertext Preprocessor) est un langage de script côté serveur conçu pour le
développement web, mais également utilisé comme un langage de programmation dans des
contextes plus variés.
Le code PHP peut être intégré à du code HTML, ou utilisé en combinaison avec divers systèmes de
modèles web, des systèmes de gestion de contenu web et des frameworks web. Le code PHP est
habituellement traité par un interpréteur PHP implémenté comme un module dans le serveur web, ou
comme un exécutable (CGI - Common Gateway Interface). Le serveur web combine les résultats du
code PHP interprété et exécuté, pouvant consister en tout type de données, même des images, avec
la page web générée. Le code PHP peut également être exécuté avec une interface en invite de
commande (CLI) et peut être utilisé pour implémenter des applications graphiques autonomes.
Qu'est-ce que PHP?
L’objectif de la délimitation de tags est de séparer le code PHP des données non PHP
(principalement HTML). Bien que cette fonctionnalité soit rarement utilisée en pratique, PHP peut
exécuter du code incorporé dans tout fichier passé à son interpréteur, y compris des fichiers binaires
comme PDF ou JPEG, ou des fichiers log du serveur. Tout ce qui est hors délimiteurs est ignoré par
le parseur PHP, et retransmis tel quel dans le résultat retourné.
Ces délimiteurs recommandés créent des documents XHTML correctement formés et autres
documents XML. Cela peut être intéressant si les documents de code source doivent être traités
d’une autre manière durant la vie du logiciel.
Si la validation XML correcte n’est pas un problème, et si le fichier contient uniquement du code PHP,
il est préférable d’omettre la balise fermant (?>) à la fin du fichier.
Syntaxe et exemples
Corps
<!DOCTYPE html>
<html>
<head>
<title>PHP Test</title>
</head>
<body>
<?php echo '<p>Hello SAGE X3 World</p>'; ?>
</body>
</html>
Le processeur PHP parse uniquement le code au sein de ses délimiteurs. Tout ce qui est hors
délimiteurs est directement retransmis en output, et n’est pas parsé par PHP. Les seuls délimiteurs
d’ouverture/fermeture autorisés par PSR-1[3] sont <?php et ?> ou <?= et ?>. Dans les fichiers
contenant seulement du PHP, la balise de fin devrait être omis.
Syntaxe et exemples
Variables
Les variables, en PHP, sont représentées par un signe dollar suivi par le nom de la variable. Le nom
de la variable est sensible à la casse.
Les noms de variables suivent les mêmes règles que les autres appellations PHP. Un nom de
variable valide commence par une lettre ou un underscore, suivi par des lettres, nombres, ou
underscores en nombre quelconque. L’expression régulière correspondante est la suivante:
'[a-zA-Z_\x7f-\xff][a-zA-Z0-9_\x7f-\xff]*'
<?php
$var_tic = ‘Tic';
$var_tac = ‘ et Tac';
echo "$var_tic, $Var_tac"; // outputs « Tic et Tac »
$4site = 'not yet'; // invalid; starts with a number

$_4site = 'not yet'; // valid; starts with an underscore
$täyte = 'mansikka'; // valid; 'ä' is (Extended) ASCII 228.
?>
Syntaxe et exemples
Instructions conditionnelles
If ... else[edit]
La syntaxe en PHP d’une instruction If ... else est la suivante:
<?php
if (condition) {
// instructions;
} elseif (condition2) {
// instructions;
} else {
// instructions;
}
?>
Code PHP pour appeler un Web Service X3
Lecture de la Liste de Clients et d’une Commande Unique
Lecture de la liste de clients (liste de gauche de Lecture d’une simple commande:

l’objet Commandes de Vente) :
<?php
<?php …
… $order = new Order ();
$order = new Order (); echo ($order->showOne ( $sohnum ));
echo ($order->showListe ()); …
… ?>
?>
Appel d’un Web Service en PHP
Création d’une commande
Création d’une commande ($WS paramètres d’input pour le web service):
<?php
…
$WS = "<PARAM><GRP ID=\"SOH0_1\" >";
$WS .= "<FLD NAME=\"SALFCY\">$formsalfcy</FLD>";
$WS .= "<FLD NAME=\"SOHTYP\">$formsohtyp</FLD>";
$newDate = date ( "Ymd", strtotime ( $formorddat ) );
…
$WS .= "<FLD NAME=\"BPCORD\">$formbpcord</FLD>";
$WS .= "</GRP>";
$WS.="<TAB ID=\"SOH4_1\">";
for($i = 0; $i < count ( $formtabitmref ); $i ++) {
$WS .= "<LIN>";
$WS .= "<FLD NAME=\"ITMREF\">$formtabitmref[$i]</FLD>";
$WS .= "<FLD NAME=\"QTY\">$formtabqty[$i]</FLD>";
$WS .= "</LIN>";
}
$WS .= "</TAB></PARAM>";
Appel d’un Web Service en PHP
Création d’une commande
Création d’une commande (Exécution d’un web service):
$order = new Order ();

echo ($order->create ( $WS ));
…
?>
Ressources Sage
Pour installer le site web, tout se trouve sur le site:
https://github.com/Sage-ERP-X3/sample-x3-ws-php-webportal
La documentation est disponible soit en pdf ou directement en ligne.

Installation et configuration du Portail Web
Recommandation:
Suivez le guide pas
à pas
Présentation du portail web PHP
Entrez l’url de votre portail dans votre navigateur par défaut. Dans cet exemple, l’URL est
http://x3pu9trainvm:8125/sagex3/
C’est le nom du serveur X3 Syracuse; le numéro est configuré dans httpd.conf.
Ceci est un exemple de rendu de votre portail.
Avertissement
• Ce portail est un portail de démo basé sur Wampserver.
• WampServer est un outil de développement

• L’utilisateur principal MySQL et son mot de passe ne sont pas sécurisés,
• Le serveur Apache n’est pas accessible à l’extérieur de la machine serveur
• Ce portail PHP peut être attractif, mais dans ce cas, le serveur web doit être un vrai serveur de
production.
• Le code PHP n’est qu’un exemple pour les développeurs. Ne le réutilisez pas pour un portail de
production. Le code PHP de ce portail n’a pas été écrit par un spécialiste PHP.
Comment (re)démarrer le serveur Wamp
Démarrez Wampserver
Redémarrez Wampserver
Eclipse PHP pour développement
Installation
Téléchargez
Eclipse pour
PHP 64 bit
Installation
• Ouvrez Eclipse
• Nouveau projet PHP

Installation
• Nom de projet sagex3

• Création d’un projet à une
location existante
• Cliquez sur Finish
• Visionnez PHP explorer
3 – Architecture de Web
Service Sage X3
• Solution X3
• Serveur web
• Pool de connexion
• Publication de Web Services
40
© 2016 Sage Software, Inc. All rights reserved
La solution Sage X3
Ce que vous devez savoir
Les Web Services sont liés à une solution X3.
Une solution est une installation Sage X3 unique et identifiée contenant:
• Une plateforme de technologies (Runtime, Database Server, Serveur Web etc.)
• Une hiérarchie de dossiers (Dossier de référence → Dossiers enfants)
• Eléments de la base appartenant à chaque dossier
• Des répertoires sur le serveur d’application
Une installation X3 (Solution) est identifiée par un nom et un code, défini dans la console et stocké
dans le fichier solution.xml, dans le répertoire parent du répertoire de référence (typiquement le
répertoire …/Folders ).
Différentes solutions X3, sur différentes machines ou sur la même, peuvent avoir des dossiers avec le
même nom publiés sur les mêmes serveurs Web. Le nom de la solution permet alors de les
différencier.
41
La solution Sage X3
Architecture de la solution Sage X3
HTTP/HTTPS Web Client

(SOAP/REST)
Database Web
Server Server
Process Apps
server
Application
Server
42
Web Serveur Sage X3
Le Web Serveur Sage X3 publie des Web Services
X3 Serveur Web X3 Application

NODEJS Server
n simultaneous
permanent
connexions
X3 instruction
JSON WS Pool de Connexion

Third-Party
XML (SOAP) Interpretation Applications
Apps (Java, .NET,
JavaScript, PHP etc.)
43
Traitement de requêtes par le Web Service
1. Action utilisateur : L’utilisateur X3 Application Server

requiert des infos, presse le bouton 4 3
du site web, etc…
WEB Server
2. Le site web appelle l’URL du web Sage Protocol
service X3 avec les paramètres
corrects (http/SOAP) 5
3. Le serveur web X3 contacte le
serveur d’application et déclenche le
process (protocole X3)
4. Le process X3 est exécuté par le
serveur d’application (Appel de 2 6
sous-programme, action objet etc.)
5. Le serveur d’application X3 retourne
des résultats au serveur web X3
(protocole X3)
6. Le serveur Web retourne les
données au site web (http/SOAP) Utilisateurs
1 1
Internet / Intranet
7
Web Site
44
Le pool de connexion
Qu’est-ce que le pool de connexion?

• Un ensemble de connexions X3 permanentes avec le serveur d’application, utilisées lorsque nécessaire par le
serveur web: Canaux
• Les outils et mécanismes pour gérer les files d’attentes de requêtes au web service, et la manière dont les
connexions disponibles sont utilisées pour traiter les requêtes.
Le pool de connexion est initialisé avec un nombre prédéfini de connexions.

Pool de Connexion
Serveur de Connexion X3 Manager Requête 1
Requête 2
> Commence automatiquement avec le serveur web X3
> Démarre manuellement depuis la page administration
X3 Serveur Web
N Connexions Permanentes
45
Pool de Connexion
Fonctionnement
• Des requêtes peuvent arriver simultanément sur le site web.
• Les requêtes sont mises dans une file d’attente jusqu’à ce qu’une connexion soit disponible.
• Lorsqu’une connexion est disponible, le serveur web utilisera cette connexion pour traiter la
requête la plus avancée dans la file d’attente (ordre FIFO)
• L’algorithme de distribution du pool optimise l’utilisation des connexions disponibles en
fonction de l’utilisateur, du langage, du dossier etc… spécifiés.
• Le nombre total de connexions est spécifié dans le Serveur Web.
SERVEUR DE WS POOL
Requête 1
TRAITEMENT Connexions (Canauxs)
Requête 2
Requête 3
File Requête 4
d'attente Requête 5
46
Pool de Connexion
Fonctionnement
E.G: requêtes avec le même utilisateur et 3 langages.
• Les chaînes s’adapteront aux requêtes de manière à rester ouvertes sans changer de contexte
SERVEUR DE WS POOL
TRAITEMENT Connexion #0 (Canaux)
ADMIN Requête 1- ENG
ENG
Connexion #1 (Canaux)
ENG
ENG
47
Pool de Connexion
Fonctionnement
SERVEUR DE WS POOL
ADMIN Requête 1- FRA
ENG
FRA
ENG
48
Pool de Connexion
Fonctionnement
SERVEUR DE WS POOL
ENG
FRA
FRA
49
Pool de Connexion
Fonctionnement
SERVEUR DE WS POOL
ENG
FRA
ENG
50
Pool de Connexion
Que sont les traitements enfants?
Un traitement niveau nœud qui gère les canaux
• Au moins un enfant sur l’hôte Syracuse: W0
51
Pool de Connexion
Configuration par défaut pour un pool donné.
Canaux
WS Pool Processus #1
WSLIVE1 Enfant W0 Canaux
#2
52
Pool de Connexion
Autoriser la balance de charge (basée sur la disponibilité des processus Wn)
Canaux #1
Child
Process W0
Canaux #2
WS Pool
WSLIVE1
Canaux #1
Child
Process W1
Canaux #2
53
Pool de Connexion
Un traitement niveau nœud qui gère les canaux

• Multiplier le pouvoir de traitement
EG: 2 canaux 2 canaux
x 1 traitement enfant x 2 traitement enfants
________________ ________________
= 2 canaux = 4 canaux
• Equilibrage de la Charge des Requêtes (Round Robin)
54
Publication de Web Services X3
Serveur
Serveur d’application X3 Web Client Application
Sous-programmes
Web Service Publication Utility

(X3 Code) SOAP Message
Méthode: Description XML
run() Web URL
Arguments
X3 Objet
(Clients, Ventes
Commandes,
Produits, Objets
spécifiques…)
Programme
Méthodes: enveloppant
read() +
save()
Programme
delete()
… Test
55
L’utilitaire de publication (Développement / Processus / Processus/ Web Services)

• C’est une fonction très simple qui transforme un sous-programme ou objet en un web service avec
un nom public, et génère sa description XML, stockée dans le répertoire
X3_PUB/<FolderName>/GEN/ALL/WEBS sur le serveur d’application.
• Il est également possible de lister les web services publiés (pour le dossier), de dé-publier les web
services, ou de générer tous les web services définis pour le dossier (Publication Globale)
• Les web services générés ont un time-stamp, et le serveur web vérifiera toujours si la version qu’il
a dans son cache est la dernière version. Dans le cas contraire, il rechargera la dernière version
du serveur d’application.
56
Programme encapsulant
L’utilitaire de publication génère également un programme encapsulant en code X3, qui fait
l’interface entre X3 et le serveur web. Le programme encapsulant est appelé:
• WJ[WS_NAME] pour les objets, où [WS_NAME] est le nom public de l’objet (Web Services).
• WJ[WS_NAME] pour les sous-programmes, où [WS_NAME] est le nom public du sous-
programme (Web Service name).
Le programme encapsulant gère:
• Les arguments d’entête (données techniques, timestamps etc.)
• Messages
• Flux de données, entrants et sortants.
Le programme encapsulant contient un sous-programme de test automatique qui permet au
développeur de faire tourner le web service en X3 avant de l’utiliser depuis une application externe.
57
4 – Paramétrage des
Web Services
• Configuration du serveur X3
• Configuration du pool de web services
• Licences du serveur web
58
Configuration du serveur X3
Ouvrir Administration > Administration > Serveurs > Hôtes.

Cliquer sur l’icône d’édition à côté du nom de l’hôte.
Sur l’écran suivant, dans le champ Nombre de traitements web-services enfants, entrez une valeur
(1 minimum)
59
Configuration du Pool de Web Services X3
Ouvrez Classic SOAP pools configuration dans Administration > Administration > Web Services.
Cliquez sur Create soapClassicPool.
Complétez les champs suivants:
- Alias: Entrez le nom du pool à utiliser dans l’appel au web service.
- Taille d’initialisation: Entrez 1 ( minimum).
Représente le nombre de clients (par process de nœud.js) qui sont initialisés durant le
démarrage du pool.
- Taille maximale: Entrez 1 ( minimum).
Représente the nombre maximal de clients (par process de nœud.js) pouvant être lancés
dans ce pool.
60
Auto start: Cocher. → si coché, le pool commence dès le démarrage du serveur Syracuse.
X3 server TAGS: Ne pas renseigner. → Pour choisir le même TAG que le TAG du runtime.
Endpoint: Saisir le endpoint (dossier) à utiliser pour les requêtes de web service.
Locale: Saisir votre langage et localisation (Dans cet exemple, Anglais.)
User: Saisir le nom de l’utilisateur, Admin par exemple. Il est préférable de saisir un utilisateur dédié
aux web services exclusivement.
61
TAGS Serveur X3
• Administration / Endpoints / solutions X3 • Administration / Configuration des pools
• TAG serveur X3 classiques SOAP
• X3 server TAG
62
63
Licences Serveur Web
Installation
Basé sur le volume de données consommé.

Administration > Administration > Licences > License data
• Données considérées : le flux est considéré dans son entièreté, input et output, sauf pour les TRACES, qui
sont exclues du calcul. Lorsque vous utilisez le testeur de graphes interne, la consommation est ignorée.
• WSSIZELIMIT: définit la taille (en Megabytes) de données pouvant être échangées dans les web services
SOAP entrants.
• WSPERIOD: définit la période à laquelle la limitation de taille s’applique (une chaîne pouvant être DAY,MONTH
ou YEAR).
• WSGRACELIMIT: (pourcentage) définit le pourcentage de dépassement de taille autorisé (typiquement 10%);
cela signifie que si la taille maximale est définie comme 1MB/jour, 1.1 MB par jour sera possible sans blocage
des web services.
• WSGRACESLOWDOWN: décrit le taux utilisé pour décroître la vitesse des web services entre la taille limite et
la taille limite augmentée de la marge de dépassement autorisée. Si, par exemple, ce paramètre vaut 5, cela
signifie que lorsque la limite de 1MB aura été dépassée, la vitesse sera divisée par 5 jusqu’à la fin de la
journée, ou jusqu’à ce qu’on atteigne la limite 1.1MB; alors, les web services s’arrêteront pour la journée.
64
Installation
Exemple:
• WSSIZELIMIT : 1 MB
• WSPERIOD : DAY
• WSGRACELIMIT : 10 % = 0,1 MB
• WSGRACESLOWDOWN : 5
• [0MB ; 1MB] → Vitesse normale

• ]1MB ; 1,1MB] → Vitesse diminuée. (divisée par 5)
• >1,1MB → Arrêt du web service
65
Notification pour licence
• Administration / Paramétrage / Paramétrage global
• Administration / Collaboration / Evénements de Notification
license_web_warn Cet événement est lancé lorsque la limite en volume des données allouée
aux web services par la licence est significativement proche de la limite
réelle. L’objectif est de rappeler à l’utilisateur qu’il/elle devrait faire
attention à la limite et peut-être améliorer les termes de la licence.
Dans l’aide en ligne :

License_web_max, license_web_grace
66
Installation
WEB SERVICES
UTILISATION GRATUITE
JUSQU’À NOUVEL ORDRE
67
5 – Publication et Test
• Publier des sous-programmes

• TP 1 “Liste de clients”
• Test des sous-programmes
• Publication Objet
• TP 2 “Publication Objet SOH”
• Test objet WS pour le portail PHP
• TP 3 – Web service YOSOH
• Log web service
25/02/2019 68
Publication de sous-programmes
Sous-programme
Dictionnaire
Introduction
• Un sous-programme doit être déclaré dans le Dictionnaire des sous-programmes
(Développement / Dictionnaire de Scripts / Scripts / Sous-programmes) de manière à être utilisé
comme un web service.
• Le dictionnaire liste les arguments du sous-programme (détecté automatiquement à partir du

code).
• Un sous-programme appelé comme un Web Service peut retourner des valeurs à l’entité
appelante via certains de ses arguments, passés par adresse plutôt que par valeur.
70
Sous-programme
Dictionnaire
Génération de messages dans un sous-programmes
Il est possible de générer des messages et de les envoyer au serveur web durant l’exécution d’un
sous-programme. Pour s’assurer que les messages sont correctement générés, vous devez toujours
utiliser les appels suivants:
• Message d’information: Call MESSAGE(MESSAGE) From GESECRAN

• Message d’avertissement: Call ADDMESSWARN(MESSAGE) From AWEB
• Message d’erreur Call ERREUR(MESSAGE) From GESECRAN
Les messages sont transmis dans les données de la réponse XML et peuvent être utilisés par
l’application côté client.
Un unique sous-programme peut générer jusqu’à 50 messages.
71
Publier dans un sous-programme
Utilitaire de publication
• Pour publier un sous-programme, vous devez simplement définir le nom public du Web Service.
• L’utilitaire de publication générera le fichier de description XML sur le serveur d’application, dans le
répertoire suivant: X3_PUB/<FolderName>/GEN/ALL/WEBS
• Le programme encapsulant est également créé avec le nom suivant : WJ[WS] où [WS] est le nom
public du web service.
72
Cas pratique 1
“Liste de clients”
Notre sous-programme d’exemple ira chercher une liste de clients (codes, noms et limite de crédit)
depuis la table clients X3 (BPCUSTOMER).
Un intervalle de codes clients et un nombre maximal de clients peut être envoyé comme arguments
d’input.
73
Cas pratique 1
• Trouvez le script XLISTBPC.src
• Compilez-le et sauvez-le sous le nom XLISTBPC
• Créez la description de ce sous-programme dans le dictionnaire:
• Développement > Dictionnaire de Scripts > Scripts > Sous-programmes (GESASU)
- Processus: XLISTBPC
- Sous-programme: LISTBPC
• La liste de paramètres est chargée automatiquement.
• Description: Liste de clients
• Web Services
• Le nombre renseigné dans la colonne dimension pour BPCNUM, BPCNAM et OSTAUZ doit être le nombre de
clients que l’on désire afficher (NBBPC).
74
•
Cas pratique 1
• Onglet définition, Nom de publication: WSLISTBPC
• Vérifiez l’onglet de mapping; que voyez-vous dans les colonnes de groupe et de niveau?
• Dans l’onglet Définition, notez le nom du programme encapsulant dans le bloc d’information.
• Ouvrez le programme encapsulant et exécutez-le
75
©
Cas pratique 1
Script XLISTBPC
#**
#* BPCLIST: Liste de clients pour Web Services
#* @param BPCSTR Borne inférieure
#* @param BPCEND Borne supérieure
#* @param NBBPC Nombre de clients dans la liste (dimension)
#* @param BPCNUM Code client
#* @param BPCNAM Nom du client
#* @param OSTAUZ Crédit du client
#*!
Subprog LISTBPC(BPCSTR,BPCEND,NBBPC, BPCNUM, BPCNAM, OSTAUZ)
…
End
76
Cas pratique 1
Êtes-vous prêt à pratiquer?
Cas pratique 1
► Compilez-le et sauvez-le sous le nom XLISTBPC
► Créez la description de ce sous-programme dans le dictionnaire
► Créez le web service WSLISTBPC
► Publiez le web service
► Ouvrez le programme encapsulant et exécutez-le
78
Cas pratique 1
► Compilez-le et sauvez-le sous « XLISTBPC » dans Eclipse
Compiler
79
Cas pratique 1
► Créez la description de ce sous-programme dans le dictionnaire 1/2
Code activité
préalablement créé
N’oubliez pas
cette case
80
Cas pratique 1
► Créez la description de ce sous-programme dans le dictionnaire 2/2
► N’oubliez pas de mettre une dimension >1 pour les tables de valeurs de retour
81
Cas pratique 1
► Créez le web service WSLISTBPC
82
Cas pratique 1
Publiez
83
©
Cas pratique 1
► Ouvrez le programme encapsulant et exécutez-le dans X3
84
©
Cas pratique 1
► Ouvrez le programme encapsulant et exécutez-le dans le fichier de logs X3.
85
©
Sous-programmes de test - Outil X3
Sous-programmes de test - Outil X3
Test du Web Service « Liste de clients »
Outil X3– Administration / Web Services / Web services SOAP classique
87
Outil X3
Outil X3 – Administration / Web Services / Web services SOAP classique
88
Outil X3 - Exécution
Outil X3– Administration / Web Services / Web services SOAP
classique
Cliquez sur Exécuter
• Code du langage: langage (FRA, ENG, BRI...)
• Alias de Pool: Code de Pool (ex : SEED)
• Pool ID: vous permet de forcer un client spécifique à
travers une définition de pool
• Configuration de requête :
adxwss.beautify=true&adxwss.optreturn=JSON
• Nom Public: Nom du web service
89
• Input XML/JSON:
{ "GRP1" : {
"BPCSTR": "",
"BPCEND": "",
"NBBPC": "0"
}
90
Retour du Web Service
• Status : 0 = NOK, =1=OK à l’exécution du Web Service
91
Test du Web Service: Liste de clients
Outil X3 - Exécution Result XML/JSON:
Retour du Web Service {
"GRP1": {
"BPCSTR": "",
"BPCEND": "",
"NBBPC": "0"
},
"GRP2": [
{
"BPCNUM": "",
"BPCNAM": "",
"OSTAUZ": "0"
}
]
} 92
Configuration de la requête:
Un ensemble de configurations séparées par le caractère '&' :
adxwss.trace.on: valeur 'on' activée
adonix.trace.level : Entier définissant le niveau des traces de l’exécution.
adonix.trace.size: Entier définissant la taille des CLOB durant l’exécution.
adxwss.optreturn : Peut être 'XML' ou 'JSON'. La valeur par défaut est 'XML'.
adxwss.beautify: Peut être 'true' ou 'false'. Mis à ‘true’, le flux de retour est formaté pour être plus
lisible.
93
Le programme encapsulant
Utilisation du programme encapsulant
• Le programme encapsulant contient du code de test permettant de s’assurer du bon

comportement du sous-programme (simplement en exécutant le programme encapsulant).
• Le code de test génère un fichier de trace générique avec les résultats.
• Deux sections, $INITWS et $RESULTWS, peuvent être insérées dans le sous-programme initial,
dans lesquelles on peut initialiser les arguments et ajouter des lignes supplémentaires dans le
fichier de trace. Si elles existent dans le sous-programme initial, elles sont automatiquement
appelées.
• Il est recommandé d’implémenter votre code de test et vos modifications dans un traitement
séparé, puisque le programme encapsulant est re-généré à chaque fois que le web service est
republié.
94
Sous-programmes de test – Outil Soapui
Test du Web Service « Liste de clients »- Outil Soapui
Vous pouvez utiliser l’outil open-source Soapui.

Téléchargez-le et installez-le: https://www.soapui.org
97
Obtenez le fichier de description wsdl dans X3
98
Copiez l’url
99

L’url est, par exemple:
http://x3pu9trainvm/soap-wsdl/syracuse/collaboration/syracuse/CAdxWebServiceXmlCC?wsdl
100
Créez un nouveau projet SOAP
Fichier wsdl
101
Test du Web Service « Liste de clients »- Outil Soapui -
Exécution
Renommez la requête web service Requête_Liste_de_Clients.
Double-cliquez pour ouvrir cette requête
102
Test du Web Service « Liste de clients »- Outil Soapui –
Exécution
Modification du flux xml en input
<soapenv:Envelope
…
<codeLang xsi:type="xsd:string"> ENG </codeLang>
<poolAlias xsi:type="xsd:string"> SEED </poolAlias>
<poolId xsi:type="xsd:string"></poolId>
<requestConfig xsi:type="xsd:string"></requestConfig>
</callContext>
<publicName xsi:type="xsd:string"> WSLISTBPC </publicName>
<inputXml xsi:type="xsd:string"> … </inputXml>
…
103
Exécution
Modification de la balise xml en input

<inputXml>
<inputXml xsi:type="xsd:string">
<![CDATA[
{ "GRP1" : {
"BPCSTR": "AO01",
"BPCEND": "ES001",
Vous devez entourer json
"NBBPC": "5" avec
} <![CDATA[ … ]]>
}
]]>
</inputXml>
104
Test du Web Service « Liste de clients »- Soapui - Exécution
Obligatoire pour se connecter à X3.
Username : utilisateur X3
Password : mdp X3
Pré-emptive auth: Authentification
prioritaire
Exécution
Retour du web service

Retour XML/JSON
{<resultXml xsi:type="xsd:string">{
"GRP1": {
…} Statut du web service :
1 = OK
</resultXml>
0 = NOK
<status xsi:type="xsd:int">1</status>
106
Exécution
Statut NOK du Web Service

• Input <inputXml> vide
• Retour XML/JSON vide
• Statut: 0
107
Test du Web Service: Liste de clients - Outil Soapui -
Exécution
Résultat NOK du Web Service
• Message d’erreur
108
GetDescription
XLM input
XML Output
109
GetDescription
Description de l’output XML. Pas de description JSON dans la balise <resultXml>:
<ADXDOC …>
<ADXDATA>
<GRP PNA="GRP1" NAM="GRP1" DIM="1">
<FLD NAM=“BPCSTR“ IDX=“1“ TYP=“Char“ PAR=“Value“ MOD=“Input“ LEN=“250“ C_ENG=“Start range“ >
<FLD NAM=“BPCEND“ IDX=“2“ TYP=“Char“ PAR=“Value“ MOD=“Input“ LEN=“250“ C_ENG=“End range“ >
<FLD NAM=“NBBPC“ IDX=“3“ TYP=“Integer“ PAR=“Value“ MOD=“Input“C_ENG=“Number of customer“ >
</GRP>
<GRP PNA="GRP2" NAM="GRP2" DIM="100">
<FLD NAM=“BPCNUM“ IDX=“4“ TYP=“Char“ PAR=“Adr“ MOD=“Input“ LEN=“250“ C_ENG=“Customer code“ >
<FLD NAM=“BPCNAM“ IDX=“5“ TYP=“Char“ PAR=“Adr“ MOD=“Input“ LEN=“250“ C_ENG=“Customer name“ >
<FLD NAM=“OSTAUZ“ IDX=“6“ TYP=“Decimal“ PAR=“Adr“ MOD=“Input“C_ENG=“Customer credit“ >
</GRP>
</ADXDATA>
<ADXMEN> ... </ADXMEN>
</ADXDOC>
110
GetDescription
{
"GRP1": {
Input-Output JSON "BPCSTR": "AO01",
"BPCEND": "ES001",
"NBBPC": "5"
},
"GRP2": [
{
"BPCNUM": "AO021",
"BPCNAM": "Agro Alimentar do Namibe",
"OSTAUZ": "0"
},
{
"BPCNUM": "AO151",
"BPCNAM": "Luanda Bikes",
"OSTAUZ": "0"
},
{
"BPCNUM": "AO152",
"BPCNAM": "SoftCenter - Informatica ",
"OSTAUZ": "0"
}
]
}
111
GetDescription
Input-Output XML
<ADXDATA>
<GRP NAM="GRP1"> For Input XML For Output XML
<FLD NAM=“BPCSTR“ TYPE=“Char“/>
<ADXDATA> → <PARAM> <ADXDATA> → <RESULT>
<FLD NAM=“BPCEND“ TYPE=“Char“/> </ADXDATA> → </PARAM> </ADXDATA> → </RESULT>
<FLD NAM=“NBBPC“ TYPE=“Integer“/>
</GRP>
<GRP DIM="100“ NAM="GRP2" SIZE=“5">
<LIN NUM="1”>
<FLD NAM=“BPCNUM“ TYPE=“Char“ />
<FLD NAM=“BPCNAM“ TYPE=“Char“ />
<FLD NAM=“OSTAUZ“ TYPE=“Decimal“ />
</LIN>
<LIN NUM=“2”>
<FLD NAM=“BPCNUM“ TYPE=“Char“ />
<FLD NAM=“BPCNAM“ TYPE=“Char“ />
<FLD NAM=“OSTAUZ“ TYPE=“Decimal“ />
</LIN>
</GRP>
</ADXDATA>
112
Test du Web Service « Liste de clients »- Outil X3
Qu'est-ce que le format JSON?
JSON: JavaScript Object Notation.
JSON est une syntaxe pour stocker et échanger des données.
JSON est plus facile d’usage que XML.
JSON: Exemple:
{"employees":[
{"firstName":"John", "lastName":"Doe"},
{"firstName":"Anna", "lastName":"Smith"},
{"firstName":"Peter", "lastName":"Jones"}
]}
113
Règles de syntaxe JSON
• Les données sont rangées en paires nom/valeur

• Les données sont séparées par des virgules
• Les objets sont délimités par des accolades
• Les tableaux sont délimités par des crochets
Exemple JSON :
"firstName":"John"
Une donnée JSON- Un nom et une valeur
Les données JSON sont rangées en paires nom/valeur.
Exemple JavaScript :
Une paire nom/valeur consiste en un champ nom
firstName :"John"
(entre guillemets) suivi de deux points, suivis d’une valeur.
Les noms JSON nécessitent des guillemets doubles,

contrairement aux noms JavaScript.
114
Valeurs JSON Objets JSON

Les valeurs JSON peuvent être: Les objets JSON sont écrits entre accolades.
• Un nombre (entier ou décimal) Comme en JavaScript, les objets JSON peuvent contenir
• Une chaîne (entre guillemets doubles) plusieurs paires nom/valeur.
• Un booléen (vrai ou faux) Exemple:
• Un tableau (entre crochets) {"firstName":"John", "lastName":"Doe"}
• Un objet (entre accolades)
• null
Tableaux JSON
Les tableaux JSON sont écrits entre crochets.
Comme en JavaScript, un tableau JSON peut contenir plusieurs objets.
Exemple:
"employees":[
{"firstName":"John", "lastName":"Doe"},
{"firstName":"Anna", "lastName":"Smith"},
{"firstName":"Peter","lastName":"Jones"}
]
115
Description JSON
Input / Output pour sous-programmes X3
Le groupe GRPn est de dimension 1 Le groupe GRPm est de dimension > 1
[ ] est une table.
“GRPn” : { "GRPm": [
“Field1” : “value string”, {
“Field2” : number “Field1” : “value string 1”,
} “Field2” : number 1
},
{
“Field1” : “value string 2”,
“Field2” : number 2
}
]
116
Description XML
Le groupe GRPn est de dimension 1
<GRP ID="GRPn" DIM="1">

<FLD NAME="STOCK“ TYPE="Decimal">
Valeur du champ
</FLD>
</GRP>
<GRP ID="GRPn">
<FLD NAME="STOCK“>
Valeur du champ Format d’input simplifié
</FLD>
</GRP>
117
Description XML
<TAB DIM=“1000“ ID=“GRP2“ SIZE=“5“>

Le groupe GRP2 est de
<LIN NUM=“1“>
dimension > 1 ( dim = 1000)
<FLD NAME="STOCK“ TYPE="Decimal">Value of field 1</FLD>
</LIN>
<LIN NUM=“2“>
<FLD NAME="STOCK“ TYPE="Decimal">Value of field 2</FLD>
</LIN>
</TAB>
<TAB ID=“GRP2“>
<LIN NUM=“1“>
<FLD NAME="STOCK“>Value of field 1</FLD>
</LIN>
<LIN NUM=“2“>
Format d’input simplifié
<FLD NAME="STOCK“>Value of field 2</FLD>
</LIN>
</TAB>
118
XML/Description JSON
Pour un input XML Pour un input JSON

<![CDATA[ <![CDATA[
<PARAM> {
… …
</PARAM> }
]]> ]]>
Pour un output XML Pour un output JSON

<![CDATA[ <![CDATA[
<RESULT> {
… …
</RESULT> }
]]> ]]>
119
Publication d'objets
Le Dictionnaire des Objets
Les objets X3 (Produits, Commandes de vente, Fournisseurs, etc.) sont stockés dans un dictionnaire décrivant:
• Le navigateur de gauche (Paramètres de Sélection)
• Les écrans d’objet (Champs, blocs etc.)
• Options spéciales / boutons / menus
• La table principale de l’objet
• Les traitements X3 liés à l’objet
Pour publier un objet, il n’est habituellement pas nécessaire de modifier le dictionnaire. Si l’objet est disponible
en mode TP, il devrait également l’être à travers les Web Services.
Cependant, des modifications minimes peuvent s’avérer nécessaires pour accéder aux écrans de saisie
supplémentaires, comme l’écran des adresses dans les Commandes de Vente. Ces modifications se font via
l’option Ecrans Supplémentaires du dictionnaire des objets.
Le modèle objet est le type de fonction le plus utilisé dans X3. D’autres fonctions n’appartenant pas à ce
modèle (par exemple des fonctions standard comme la Validation Automatique de Factures) peuvent
habituellement être encapsulées dans des sous-programmes pouvant être appelés via des Web Services.
121
Types de champs
Les champs d’objet peuvent être:
• Saisissables: Le champ est utilisé et transmis dans les Web Services ainsi que dans les clients
traditionnels.
• Affichés: Le champ est transmis dans les Web Services ainsi que dans les clients traditionnels.
• Invisibles: Les champs invisibles ne sont jamais transmis aux clients traditionnels. Pour les Web
Services, vous avez le choix de publier ou non ces champs.
• Techniques: Ces champs ne sont jamais transmis ni aux clients, ni aux applications de Web
Services.
Les champs invisibles et techniques sont disponibles dans les classes [M] :
→ Ne pas les transmettre aux clients réduit le trafic réseau.
122
Actions de champ
Un type d’exécution est attaché à chaque action de champ dans le dictionnaire des écrans (champ
Exécution):
• Interactive: L’action est exécutée seulement chez les clients traditionnels.
• Toujours: L’action est exécutée chez les clients traditionnels et en mode web service.
• Import / Web Service: Exécuté uniquement en import et mode web-service (non interactif).
-Les actions suivantes ne sont jamais exécutées en mode web service:

• Bouton Init
• BoutonN
• Sélection
• Clic (Icônes)
123
Générateur de Web Services
L’utilitaire de publication de web services publie des objets X3 avec les choix suivants:
• Code de saisie de transaction (si disponible). Habituellement, les transactions de saisie
simples sont conçues pour les web services.
• Inclusion de champs invisibles: Les champs invisibles peuvent ou non être inclus dans l’objet
web services (les champs techniques ne sont jamais publiés).
L’utilitaire de publication génère le fichier de description XML sur le serveur d’application, dans le
dossier:
X3_PUB/<FolderName>/GEN/ALL/WEBS.
Le programme encapsulant est également créé, sous le nom suivant:

WJ[WS_NAME] où [WS_NAME] est le nom de publication du web service.
124
Cas pratique 2
“Publication d'objets SOH”
Cet exemple va publier l’objet SOH avec la transaction WEB.
125
Cas pratique 2
Fonction Développement > Dictionnaire de Scripts > Scripts > Web Services
Nom de publication: WSORDER
Description: Commandes de Vente
Objet: SOH
Transaction: WEB
• Dans l’onglet Définition, notez le programme encapsulant dans le bloc information.
• Ouvrez le programme encapsulant WJWSORDER et exécutez-le.
Note: Si vous recevez un message d’erreur "Trop de champs publiés”, réduisez le nombre de
lignes de la grille SOH4
126
Cas pratique 2
Êtes-vous prêt à pratiquer?
Cas pratique 2
► Créez le web service WSORDER

► Ouvrez le programme encapsulant et exécutez-le
128
Cas pratique 2
► Créez le web service WSORDER
129
Cas pratique 2
Publiez the web service
► Création
► Sauvegarde
► Publication
130
Cas pratique 2
► Si vous avez cette erreur,
Vous devez désélectionner des champs dans transaction de saisie WEB.
131
Cas pratique 2
► Ouvrez le programme encapsulant et exécutez-le.
132
Cas pratique 2
► Ouvrez le programme encapsulant
et exécutez-le dans le fichiers de logs X3
► C’est la liste de gauche
133
Objets de test – Outil X3
Test du Web Service: Objet SOH – Outil X3 - Requêtes
Outil X3:
Administration / Web Services / Web services SOAP classique.
Cliquez sur Requête
C’est la liste de gauche de l’objet SOH (Commandes)
Taille de liste: Nombre maximal d’enregistrements dans
la liste de gauche.
135
Test du Web Service Objet SOH - Outil X3 - Requête
Résultat retourné par le web service

• Statut : 0 = NOK, 1=OK pour l’exécution du web service
136
Test du Web Service Objet SOH - Outil X3 - Requête
Retour du Web Service
• Résultat XML/JSON
[
{
"SOHNUM": "SOWFR0120001",
"BPCORD": "FR001",
"ORDDAT": "07/09/2016",
…
},
{
"BPCORD": "FR001",
"ORDDAT": "07/09/2016",
…
}
]
137
Test du Web Service Objet SOH - Outil X3 - Lecture
Cliquez sur Read.

Pour lire un unique
enregistrement de l’objet SOH.
Cliquez ‘+’ pour ajouter la clé de
l’objet SOH.
138
Résultat retourné par le Web Service
Statut : 0 = NOK, =1=OK

pour l’exécution du web service.
139
Résultat XML/JSON
{
"SOH0_1": {
"SALFCY": "FR011",
"ZSALFCY": "Comptech SA",
"SOHTYP": "WEB",
…
"WSOHCAT": ""
},
"SOH1_1": {
"BPCINV": "FR001",
"BPINAM": "Urban Cycle",
…
140
Test du Web Service Objet SOH - Outil X3 - Sauvegarde
Click Save.
It is for creation of
an SOH record.
Object Xml: the same description (in

Xml or JSON) of the result for the Read
operation.
SOHNUM field must be empty when

creating.
141
Test du Web Service Objet SOH - Outil X3 - Sauvegarde
Status : 0 = NOK, =1=OK

for executing the web service.
142
Test du Web Service Objet SOH - Outil X3 -
Sauvegarde
The SOHNUM field has the new value of the order.
Result XML/JSON
{
"SOH0_1": {
"SALFCY": "FR011",
"SOHTYP": "WEB",
…
"WSOHCAT": ""
},
"SOH1_1": {
"BPCINV": "FR001",
"BPINAM": "Urban Cycle",
…
143
Tests - Outil Soapui
Test du Web Service: Objet SOH – Outil Soapui
Créez les requêtes de web service pour les opérations suivantes:

• Requête
• Lecture
• Sauvegarde
145
Test du Web Service: Objet SOH – Outil Soapui - Requête
Renommez la requête pour l’objet SOH
146
Modifiez le flux xml d’input
<soapenv:Envelope …
ENG </codeLang>
<codeLang xsi:type="xsd:string">ENG
SE
<poolAlias xsi:type="xsd:string">SEED
SEED </poolAlias>
ED
<requestConfigxsi:type="xsd:string">
<![CDATA[adxwss.beautify=true&adxwss.optreturn=JSON]]>
ON]]>
</requestConfig>
</callContext>
<publicName xsi:type="xsd:string">WSORDER
WSORDER </publicName>
…
147
Modifiez la balise d’input xml <listSize>

<listSize xsi:type=“xsd:int”>
10
</listSize>
N’oubliez pas l’authentification.
148
Test du Web Service: Objet SOH – Outil Soapui – Requête
Résultat retourné XML/JSON

{<resultXml xsi:type="xsd:string>
"BPCORD": "FR001",</resultXml>
<status xsi:type="xsd:int">1</status> Statut du Web Service :

1 = OK
0 = NOK
149
Test du Web Service : Objet SOH – Outil Soapui - Lecture
©
Modifiez le flux xml d'input

<soapenv:Envelope
…
<codeLang xsi:type="xsd:string">ENG</codeLang>
<poolAlias xsi:type="xsd:string">SEED</poolAlias>
ON]]> <![CDATA[adxwss.beautify=true&adxwss.optreturn=JSON]]>
</requestConfig>
</callContext>
WSORDER
<publicName xsi:type="xsd:string">WSORDER </publicName>
… 151
Modifiez la balise xml d'input <objectKeys>
<objectKeys xsi:type="wss:ArrayOfCAdxParamKeyValue"
soapenc:arrayType="wss:CAdxParamKeyValue[]">
<keys>
<key> SOHNUM </key>
<value> SOWFR0110006 </value>
</keys>
</objectKeys>
Syntaxe plusieurs keys
<objectKeys xsi:type="wss:ArrayOfCAdxParamKeyValue"
soapenc:arrayType="wss:CAdxParamKeyValue[]">
<keys> <key> …</key> <value> … </value></keys>

<keys> <key> …</key> <value> … </value></keys>
</objectKeys>
152
©2016
Test du Web Service : Objet SOH – Outil Soapui – Lecture
Résultat Web Service
Résultat XML/JSON
"SOH0_1": {
"SALFCY": "FR011",
"SOHTYP": "WEB",
…
Statut du web service :
<status xsi:type="xsd:int">1</status> 1 = OK
0 = NOK
153
Test du Web Service : Objet SOH – Outil Soapui -
Sauvegarde
154
Test du Web Service : Objet SOH – Outil Soapui - Sauvegarde
Modifiez le flux xml d'input

<soapenv:Envelope
…
<codeLang xsi:type="xsd:string">ENG</codeLang>
<poolAlias xsi:type="xsd:string">SEED</poolAlias>
<![CDATA[adxwss.beautify=true&adxwss.optreturn=JSON]]>
ON]]>
</requestConfig>
</callContext>
WSORDER
<publicName xsi:type="xsd:string">WSORDER </publicName>
… 155
Test du Web Service : Objet SOH – Outil Soapui - Sauvegarde
Modifiez la balise xml d'input <objectXml>

<objectXml xsi:type=“xsd:string”>
<![CDATA[
Pour cette partie de JSON, vous pouvez: a) obtenir le résultat de l’opération Lecture, b) initialiser le
champ SOHNUM
]]>
</objectXml>
156
Test du Web Service : Objet SOH - Outil Soapui - Sauvegarde
Modifiez la balise xml d'input <objectXml>

<objectXml xsi:type=“xsd:string”>
<![CDATA[
{
"SOH0_1": {
"SALFCY": "FR011",
"SOHTYP": "WEB",
"ZSOHTYP": "WEB",
"SOHNUM": "",
…
]]>
</objectXml>
157
Test du Web Service : Objet SOH - Outil Soapui - Sauvegarde
Le champ SOHNUM contient la clé de la nouvelle commande.
Résultat XML/JSON
"SOH0_1": {
"ZSOHTYP": "WEB",
Statut du Web Service :
"SOHNUM": "SOWFR0110007", 1 = OK
"REVNUM": "0",… 0 = NOK
<status xsi:type="xsd:int">1</status>
158
Description JSON : Input / Output pour les objets X3
Le groupe fait correspondre l’écran d’abréviations et le numéro de bloc pour un bloc liste
Code écran et numéro de bloc
"SOH0_1“ : {
"SOHNUM": “SOW001“,
“REVNUM": “0“,
“SOHTYP": “WEB“,
“SALFCY": “FR011“,
“ORDDAT": “20160907“,
“BPCORD": “FR001“,
“BPCNAM": “Urban Cycle“
}
159
Description JSON : Input / Output pour les objets
Groupe pour un bloc grille

Code d’écran et numéro de bloc
"SOH4_1“: [
{
"NUMLIG“: “0”,
"ITMREF“: “DIS010”,
"QTY“: “2”
},
{
"NUMLIG“: “0”,
"ITMREF“: “DIS010”,
"QTY“: “2”
}
160
Description XML : Input / Output pour les objets
Le groupe fait correspondre l’écran d’abréviations et le numéro de bloc pour un bloc liste
Code d’écran et numéro de bloc
<GRP ID="SOH0_1">
<FLD NAME="SOHNUM" TYPE="Char">SOWFR01100006</FLD>
<FLD NAME=“REVNUM" TYPE="Char">0</FLD>
<FLD NAME=“SOHTYP" TYPE="Char">WEB</FLD>
<FLD NAME=“SALFCY" TYPE="Char">FR011</FLD>
<FLD NAME=“ORDDAT" TYPE="Char">20160907</FLD>
<FLD NAME=“BPCORD" TYPE="Char">FR001</FLD>
<FLD NAME=“BPCNAM" TYPE="Char">Urban Cycle</FLD>
</GRP>
Le groupe pour un bloc grille
Code écran et numéro de bloc
<TAB DIM=“1002“ ID="SOH0_1“ SIZE=“2">

<LIN NUM=“1">
<FLD NAME=“NUMLIG" TYPE=“Integer">0</FLD>
<FLD NAME=“ITMREF" TYPE="Char">ITM1</FLD>
<FLD NAME=“QTY" TYPE=“Decimal">2</FLD>
</LIN>
<LIN NUM=“2">
<FLD NAME=“NUMLIG" TYPE=“Integer">0</FLD>
<FLD NAME=“ITMREF" TYPE="Char">ITM2</FLD>
<FLD NAME=“QTY" TYPE=“Decimal">3</FLD>
</LIN>
</TAB>
162
Données d’input XML des champs-tableau à l’intérieur de blocs-liste.

• Les champs-tableau à l’intérieur de blocs-liste (ex Nom de la Société dans les BPs) sont
représentés dans un élément <LST>, dont la propriété NAME contient le nom du champ.
• L’élément <LST> contient des éléments <ITM> imbriqués avec des valeurs individuelles pour
chaque index.
• Objet ITM
XML : JSON :
<GRP ID="ITM1_5"> "ITM1_5": {

<LST NAME="TSICOD"> "TSICOD": [
<ITM>20</ITM> "20",
<ITM>21</ITM> "21",
<ITM>212</ITM> "212"
</LST> ],
… …
163
XML/Description JSON : Input / Output pour les objets
Pour un input XML Pour un input JSON

<![CDATA[ <![CDATA[
<PARAM> {
… …
</PARAM> }
]]> ]]>
Pour un output XML Pour un output JSON

<![CDATA[ <![CDATA[
<RESULT> {
… …
</RESULT> }
]]> ]]>
164
Flux de données SOAP XML
Flux de données XML retournés
Statut et messages
• Le flux XML de retour contient une section qui indique le statut de la requête et potentiellement
des messages d’information, d’avertissement ou d’erreur.
Informations techniques
• Il contient également une section technique qui contient le détail des logs du traitement (si le
logging a été autorisé) et des informations de timing.
Données
• Pour toutes les méthodes de web service (objet, liste, sous-programme), le système retourne un
flux XML qui correspond, dans la description XML du web service, à l’élément <ADXDATA>
peuplé de valeurs.
• Les données sont contenues dans l’élément <RESULT> dans le flux XML retourné.
165
Flux de données XML
Vérification de l'intégrité des données
En X3, la gestion de l’intégrité des données et des conflits s’effectue au moyen de verrous symboliques. Seul un
unique utilisateur est autorisé à modifier un objet à un instant donné, et l’enregistrement est verrouillé dès que
l’utilisateur y accède.
Dans les Web Services, les méthodes Lecture et Écriture sont séparées. La méthode de lecture ne verrouille pas
l’objet (il n’y a aucun intérêt à verrouiller l’objet lorsqu’il est lu en mode web service).
Pour vérifier que l’objet n’a pas été modifié entre le moment où les données ont été lues et le moment où elles ont été
modifiées, il faut suivre la procédure suivante:
• La méthode Lecture retourne deux champs techniques inclus dans l’élément <ADXTEC> dans le flux XML de
retour:
- WW_MODSTAMP Time stamp de la mise-à-jour objet la plus récente
- WW_MODUSER Modification de l’utilisateur
• Si le champ WW_MODSTAMP est inclus dans l’input XML pour la méthode Modification, le système vérifie que
l’objet n’a pas été modifié depuis ce moment.
• Si l’objet a été modifié, un message d’erreur est retourné → (« Enregistrement modifié depuis la dernière lecture")
166
Écrans de détail/grilles
Les écrans de détail/grilles nécessitent une attention spéciale lorsqu’on y accède en mode web
service. L’exemple le plus fréquent est l’écran d’adresses dans BPs, Clients, Fournisseurs etc.
Pour y accéder via les Web Services, ces écrans doivent respecter les standards suivants:
• Code des champs de saisie (partie droite) = Caractère constant + Code du champ invisible
(Par ex XBPACRY = X + BPACRY).
• Le dernier champ numérique invisible (C) dans le bloc est la variable permettant de contrôler le
nombre de lignes. Il est initialisé par le programme encapsulant, pour chaque ligne, lorsque l’écran
est utilisé.
Seuls les champs du bloc grille (partie gauche) sont transmis via Web Service et nécessitent d’être
peuplés lors d’une création ou d’une modification. Tous les champs invisibles sont automatiquement
inclus dans la description du service web.
Lors de la modification d’enregistrements dans ces écrans, la variable de fin de grille (NBLIG,
NBADR etc.) doit être correctement alimentée. Dans le cas contraire, la dernière ligne du flux d’input
XML est considérée comme la dernière ligne d’écran.
167
Écrans supplémentaires (dictionnaire des objets)
Il est possible d’ajouter à un objet jusqu’à 8 écrans supplémentaires avec leurs abréviations
respectives.
Le système effectuera les actions suivantes:

• Inclure ces écrans dans la structure XML générée lors de la publication de l’objet.
• Ouvrir les écrans dans le traitement automatique de la fenêtre.
• Charger l’écran avec le flux XML d’input (si existant).
• Inclure les écrans dans le flux de réponse XML.
L’application (code X3) doit veiller à l’utilisation correcte de ces écrans en mode web service
(GWEBSERV=1).
L’objet standard SOH doit être modifié pour illustrer l’utilisation d’écrans supplémentaires.
168
Le programme encapsulant
Arguments d’entête
Le programme encapsulant agit comme une interface entre le serveur web et l’objet X3. Il gère:
• Les arguments d’entête

• Les messages d’information, d’avertissement et d’erreur
• Les champs objet comme arguments et valeurs de retour
Les arguments d’entête suivants sont inclus dans le programme encapsulant:

• WW_OK Integer Statut de retour: 1 (OK), 0 (Error)
• WW_ZONE Character Champ d’erreur s’il y a une erreur
• WW_STAT Integer Nombre de messages
• WW_GRAVE Integer(1..50) Niveau de message ( 1 (Info), 2 (Avertissement), 3 (Erreur) )
• WW_MESS Character(1..50) Texte de message
• WW_ACTION Character Code d’ Action/Méthode (Action à exécuter):
LECTURE / CREATION / MODIFICATION / SUPPRESSION / SUPLIG
• WW_IDENT Character Identifiant (Key1~Key2~Key3… ou valeur de départ, ou critère de
sélection rapide de la liste de gauche)
• WW_NB Integer Nombre d’enregistrements à lire (liste gauche) ou nombre d’enregistrements retournés
• WW_HORDAT Character Timestamp du web service
• WW_TAB Character Pour les actions de suppression de ligne
• WW_PAR Character Pour les actions de suppression de ligne
• WW_TRACE Clbfile Paramètres de trace pour les logs
169
Utilisation du programme encapsulant
Le programme encapsulant contient du code de test pouvant être utilisé pour s’assurer du bon
comportement de l’objet, tout simplement en exécutant le programme encapsulant avec les
paramètres corrects pour chaque action/méthode de l’objet.
Le code de test génère un fichier de trace générique avec les résultats.
Un certain nombre de sections peut être inséré dans un autre programme appelé ZZWS[OBJ]
où [OBJ] est le code objet. Si elles existent, elles seront appelées:
• $INITMAJ: Initialisation de paramètres pour les actions/méthodes de l’objet (Lecture /
Création / Modification / Suppression / Actions spéciales).
• $RESMAJ: Analyse des résultats et des lignes additionnelles du fichier de trace pour les
actions/méthodes de l’objet.
• $INITLG: Initialisation de paramètres pour la méthode de la liste de gauche.
• $RESLG: Analyse des résultats et des lignes additionnelles du fichier de trace pour la
méthode de la liste de gauche.
170
Web Service pour le portail PHP
Exemple de Site Web PHP
Web Service pour le portail PHP
Le web service utilisé pour le portail est YOSOH.

Ouvrez C:\Sage\wamp\www\sagex3\config\Config.php
Nom du web service
172
Cas pratique 3
“Exécutez le web service YOSOH
dans Soapui”
173
Cas pratique 3
• Dupliquez les requêtes Query_WSORDER en Query_YOSOH pour Requête, Lecture et
Sauvegarde
• Exécutez les requêtes ci-dessous:
174
Utilisation des logs X3 pour les web
services
Trace du serveur- Configuration
Administration / Settings / Global settings
Bloc Logs
176
• Edition
• Selection
• http
• Set Silly
177
• Selection
• Soap-generic
• Mettre la valeur Silly
- Ackcall
- Request
178
Plusieurs types d’événements sont listés dans la trace et identifiés dans la grille de
Configuration.
Pour chaque type d’événement de la trace, il est possible d’avoir plusieurs niveaux de trace:
* Erreur répertorie les erreurs trouvées.
* Warning répertorie les avertissements.
* Info Ajoute aux événements suivants les logs d’information.
* Debug C’est la trace la plus verbeuse. Retourne beaucoup d’informations
supplémentaires.
* Silly qui est la trace la plus détaillée et renvoie encore plus d'informations.
179
Trace du serveur- Visualiser les sessions de Web services
Processus Node– W0
180
Trace du serveur– Executer le web service
La sessions Node pour le web service est le Node W0.
Executer le web service YOSOH.Query. Cliquer List of orders
181
Trace du serveur – Ouvrir la trace
Ouvrir le fichier trace dans : …\SafeX3\V12SYRSVR\syracuse\logs

La dernière version :
Le detail :
2018-10-08T13:35:35.327Z | 065ad9aff650 | | 7 | http.in | info | 200 835ms "POST /soap-

generic/syracuse/collaboration/syracuse/CAdxWebServiceXmlCC"
2018-10-08T13:35:35.122Z | 065ad9aff650 | | 7 | soap-generic.request | debug | Body : <?xml version="1.0"
encoding="UTF-8"?><SOAP-ENV…</SOAP-ENV:Envelope>
182
Traces de l'hôte – Revenir au paramétrage initial
Changez le niveau à Erreur
183
6 – Mise à jour du portail
web PHP & Comment
ajouter des produits
2/25/2019 184
PHP - Liste de produits
Les corrections sont dans C:\Sage\wamp\www\sagex3\EXERCISES\1
PHP – Liste de produits
• Création du web service YOITM

• Sauvegarde
• Publication
186
• Copie de C:\Sage\wamp\www\sagex3 vers C:\Sage\wamp\www\sagex3-svg1

• Modification de C:\Sage\wamp\www\sagex3\config\Config.php.
- …
public static $WS_ORDER = "YOSOH";
Ajout
public static $WS_PRODUCT = "YOITM";
…
• Modification de C:\Sage\wamp\www\sagex3\includes\menu_home.php
187
• Ajouter le nouveau code

ci-dessous
Nouveau code
<li class="dropdown"><a href="#" class="dropdown-toggle"
data-toggle="dropdown" role="button" aria-expanded="false">Products X3
<span class="caret"></span>
</a>
<ul class="dropdown-menu" role="menu">
<li><a href="page_itm_list.php">Liste de produits</a></li>
</ul>
</li>
188
• Copie de C:\Sage\wamp\www\sagex3\page_soh_list.php vers

C:\Sage\wamp\www\sagex3\page_itm_list.php
• Mise-à-jour du fichier page_itm_list.php
• Copie de C:\Sage\wamp\www\sagex3\WebService\models\Order.php vers

C:\Sage\wamp\www\sagex3\WebService\models\Product.php
• Mise-à-jour du fichier Product.php
- Renommage de la classe Order → product
- Mise-à-jour de la fonction showListe
- $WS_ORDER → $WS_PRODUCT
- Titres de colonnes, noms de champs
189
PHP – Liste de produits - Démo
190
PHP - Détail des produits
Les corrections sont dans C:\Sage\wamp\www\sagex3\EXERCISES\2
PHP – Détail des produits
• Modification de C:\Sage\wamp\www\sagex3\WebService\models\Product.php
• Modification de la fonction showList()
• Modification de la fonction showOne()
• Copie de C:\Sage\wamp\www\sagex3\page_soh_read.php to
C:\Sage\wamp\www\sagex3\page_itm_read.php
• Modification du fichier page_itm_read.php
192
PHP – Détail des produits - Démo
Cliquer
pour
visualiser
les détails
du
produits
193
7 – Bonnes pratiques &
Performance
194
Publication
Transaction de Saisie
Il est hautement recommandé de:
• Customiser la transaction utilisée pour publier les WS.
• Réduire le nombre de contrôles d’intégrité des données X3 (moins de temps dans le
serveur d’application)
• Réduire le nombre de champs publiables (65000 max.)
• Simplifier et réduire la taille du flux XML/JSON
195
Mesure du temps d'exécution: Web Service 'Commande'
• Avec Soapui, il est facile de mesurer le temps d’exécution d’un web service
• Web service WSORDERS : Transaction normale
• Web service YOSOH : WSORDERS : Transaction simplifiée
• Résultat : la durée est divisée par 2
196
Pools de Web Services
Configuration d'un pool
• Taille et configuration de pool adaptée aux données
• Plusieurs pools (Contextes séparés: requêtes lentes/rapides, etc.)
• Plusieurs canaux par pool.
• L’application web aura besoin de connaître la configuration des pools pour répartir correctement
les requêtes.
• Changer de langage n’est pas le plus coûteux. Changer d’utilisateur est plus coûteux.
• Assurez-vous qu’il y a assez de canaux par pool:
. Recommandé: utilisateurs*langages
. 1 canal par utilisateur au moins
OU
. 3 canaux minimum pour un dossier LIVE
197
Débug et logs
Analyse et customisation du code X3

• Utilisation du débuggueur Eclipse dans une session Web Service
• Utilisation des traces serveur(déjà vues)
- Traces Syracuse
• Activez la trace pour l’appel au web service ( adxwss.trace.on=on&adonix.trace.on=on)
198
8 – Limitations des Web
Services
2/25/2019 199
Le dictionnaire de sous-programmes
Possibilités et limitations
• Les sous-programmes ne doivent pas ouvrir de fenêtre X3 pour interagir avec l’utilisateur. Ils
doivent tourner de manière indépendante et n’utiliser que leurs arguments.
• Toutes les instructions d’affichage (Affzo, Diszo etc.) sont interdites. Toutes les instructions de base
de données sont bien sûr autorisées.
• L’instruction infbox n’arrête pas le web service, mais n’envoie pas de message à l’application
cliente.
• Les emails peuvent être envoyés via l’instruction Send, ou en utilisant l’utilitaire meladx (serveur
smtp nécessaire).
• Les rapports peuvent être générés en utilisant l’instruction Report. Toujours utiliser un Serveur
d’Impression X3.
200
Publication d'un objet
Paramétrage et limitations
• Une fois qu’un objet a été publié, il doit être ajusté pour s’assurer de sa compatibilité avec les Web
Services.
• En standard, les seuls objets devant être vérifiés sont les suivants:
Commandes de Vente (SOH), Clients (BPC) Produits (ITM).
• Les autres objets doivent être vérifiés: Selon les paramètres et les actions utilisateur, des fenêtres
supplémentaires peuvent être affichées, ce qui est incompatible avec les web services.
• Les limitations principales sont liées à des problèmes d’affichage (instruction Infbox, ouverture
de fenêtres additionnelles (détail de stock, Picking dans la Liste gauche,…) )
• 65000 champs sont publiables au maximum pour les objets et les sous-programmes (Nb de
champs x Dimension)
➔ Important: utiliser une transaction de saisie dédiée et ajustée (si disponible).
201
9 – Nouveaux web
services X3 (REST)
2/25/2019 202
Introduction – Nouveaux Web Services X3
La technologie Sage X3 Version 7 introduit un nouveau type de Web Services: les Web Services
REST.
Trois types de fonctionnalités (‘facets’ en anglais) peuvent être utilisées:
• Requête
• Détail
• Edition
Dans les exemples suivants, on considère que le nom du serveur V7 est X3PU9TRAINVM.
25/02/2019 203
Outils pour tester les web services REST
• Navigateur internet ( IE, Firefox, Chrome,…)

• Extension Chrome: Postman Interceptor
• Apps Chrome Postman
• Soapui (Pour les web services SOAP et REST)
Utilisez Chrome
25/02/2019 204
Format JSON
• La plateforme de Web Services

REST est fondée sur le format
JSON.
• Il est recommandé d’utiliser une
application de visionnage JSON
correcte (notepad++) de manière à
parser facilement et
automatiquement les input/output
JSON. Des librairies dédiées sont
disponibles pour manipuler JSON
pour toutes les plateformes de
développement comme .Net ou
PHP.
25/02/2019 205
Méthodes HTTP pour web services RESTFul
Le protocole HTTP contient diverses méthodes utilisables pour les Web Services RESTful. Ces
méthodes autoriseront les opérations CRUD.
GET: est utilisé pour lire la représentation d’une ressource, par exemple la liste de commandes de
vente, ou une commande de vente
POST: est utilisé pour créer une nouvelle ressource
PUT: est utilisé pour mettre à jour une ressource existante. Il est possible de créer une nouvelle
ressource en passant la clé en paramètre d’input, mais ce n’est pas recommandé.
DELETE: est utilisé pour supprimer une ressource.
Data operation RESTful methods
Create POST
Read GET
Update PUT
Delete DELETE
25/02/2019 206
Sdata expliqué simplement
SData est un protocole Web créé par Sage qui:
• Est basé sur les normes standards, en fonction des spécifications HTTP, ATOM et JSON.
• Conforme aux principes REST.
• Est applicable à divers scénarios tels que les API, les applications mobiles ou l'intégration de tiers.
• Est libre d'utiliser.
2/25/2019 207
Les versions 7 et supérieures utilisent ce protocole entre le serveur Web Sage X3 et les différents
clients tels que les services Web, les logiciels Microsoft Office, le client mobile et le client Web avec
quelques extensions:
• Il existe deux branches de protocole:
• La première est RESTful et sans-état(« stateless ») et est utilisée lorsque les données sont
parcourues.
• La seconde est avec état (« stateful ») et n'est utilisée que lorsqu'une mise à jour est en cours. Un
identifiant unique de copie de travail (« Working copy ») identifie la ressource dans laquelle la
modification est en cours et les deltas sont échangés.
2/25/2019 208
Lorsqu'une ressource est nécessaire pour une page, il existe deux flux de données:
• Le premier renvoie le prototype. C'est la description du flux de données géré par la ressource et
correspond à la description du contrat.
• Le second est la donnée elle-même. Un flux de données peut inclure des mises à jour de
prototypes supplémentaires.
Pour plus d'informations sur SData, rendez-vous sur le site Web suivant: http://sdata.sage.com/
2/25/2019 209
Les différences entre les deux API de web services
Cet article décrit les différences entre l'API du service Web SAFE X3 et la spécification du protocole
SData 2.0.
Syntaxe URL
L'API Web SAFE X3 diffère de la syntaxe d'URL SData 2.0 comme suit:
• Les URL SAFE X3 commencent par /api1/ au lieu de /sdata/.
• Les URL SAFE X3 ont un paramètre de représentation obligatoire, qui n'est pas obligatoire dans
SData.
2/25/2019 210
L'utilisation des urls / api1 / gère le mode sans état utilisé dans les services Web:
• Chaque appel doit contenir l'en-tête d'autorisation
• Le cookie de session n'est pas utilisé
• Les sessions de gestion du service sont créées sur un pool de connexion dédié avec un court
délai pour pouvoir être rapidement libérées si elles ne sont plus utilisées
2/25/2019 211
Attention Si dans le reste du document,
Nous utilisons le mot "sdata",
Il doit être remplacé par le mot "api1" dans le cas des services Web REST
2/25/2019 212
URL: structures et paramètres
• Pour utiliser les Web Services REST, il est nécessaire de comprendre la structure de l’URL utilisée
en version 7. La version 7 implémente le protocole SDATA ou Safe X3 Web Service API.
• L’URL est définie par trois parties principales:
URL=ENDPOINT WS + Ressource + Paramètres
• Exemple SDATA:
http://X3PU9TRAINVM:8124/sdata/x3/erp/X3PU9TRAIN_SEED_LOCALDOC/SORDER?represen
tation=SORDER.$query&count=20
• Exemple Safe X3 Web Service API :
http://X3PU9TRAINVM:8124/api1/x3/erp/X3PU9TRAIN_SEED_LOCALDOC/SORDER?represent
ation=SORDER.$query&count=20
25/02/2019 213
URL: structures and paramètres
ENDPOINT WS RESOURCE PARAMETERS

http:// X3PU9TRAINVM:8124 or http:// /DIS/x3/erp/X3PU9TRAIN_SEED_LOCALD
?representation=SORDER.$query&count=20
X3PU9TRAINVM OC/SORDER
Les paramètres commencent avec le
Chemin de la classe dans votre dossier X3: caractère ?. Vous devez spécifier la
représentation liée à la classe déclarée dans
la ressource:
DIS = sdata ou api1 = nom du dispatcheur representation=SORDER
/x3 = nom de l'application
Vous devez également spécifier quelle
Serveur Syracuse auquel vous voulez vous
/erp = nom du contrat facette (méthode) vous voulez utiliser. La
connecter via le port.
facette doit commencer avec un signe $:
/ X3PU9TRAIN_SEED_LOCALDOC = nom
representation=SORDER.$query
de l’ensemble de données (Endpoint X3 )
/SORDER= nom de la classe/entité
S’il y a plusieurs paramètres, utilisez le
délimiteur & pour les lister:
representation=SORDER.$query&count=20
25/02/2019 214
URL: structures et paramètres
• Chaque facette de la représentation peut avoir

ses propres paramètres.
• Pour utiliser une facette dans les Web
Services:
• Elle doit être activée dans la
représentation
2/25/2019 215
Comment accéder aux propriétés d’une facette?
• En version 7, vous avez accès aux protocoles des ressources. Cette fonctionnalité définit les
informations requises par les facettes comme la clé à lire, l’URL à utiliser, les propriétés, etc.
• La structure de l’URL est la suivante:
http://.../$prototypes(‘MY_REPRESENTATION.$MY_FACET')
• Par exemple, pour accéder au prototype de la facette de requête de la représentation de SORDER:
http://X3PU9TRAINVM:8124/api1/x3/erp/X3PU9TRAIN_SEED_LOCALDOC/$prototypes(‘SORDE
R.$query')
25/02/2019 216
Construire l’URL pour la facette de requête
Concrètement:
• $url et $baseUrl fournissent l’URL à
utiliser pour exécuter la facette de
requête
• L’URL finale est alors: $baseUrl+$url
Toutes les facettes ont un prototype.
25/02/2019 217
Construction de l’URL pour plusieurs facettes
Facettes d’une représentation
Les prototypes sont:

• $prototypes('SORDER.$details') . Le ‘s’ est obligatoire.
• $prototypes('SORDER.$edit’)
• $prototypes('SORDER.$query')
• $prototypes('SORDER.$lookup')
• $prototypes('SORDER.$summary')
218
URL de la facette Requête – Liste de commandes
Requête – SORDER.$query
http://x3pu9trainvm:8124/api1/x3/erp/X3PU9TRAIN_SEED_LOCALDOC/SORDER?representation=SORDER.$query
25/02/2019 219
URL de la facette Détail(s)– Détail de commande
Détail(s) – SORDER(‘key’).$details
http://x3pu9trainvm:8124/api1/x3/erp/X3PU9TRAIN_SEED_LOCALDOC/SORDER('QTEFR0110040')?representation=
SORDER.$details
25/02/2019 220
Tests pour les différentes facettes
Facette Requête
Test en mode interactif

• Connectez-vous à X3 via un
navigateur (Firefox, Chrome…)
• Connectez-vous au menu de
produits (pages en lecture
seule)
• Vous pouvez voir la liste des
produits
Test avec Postman (utilisation du prototype)

• http://x3pu9trainvm/api1/x3/erp/X3PU9TRAIN_SEED_LOCALDOC/ITMMASTER?representation=ITMMA
STER.$query
Résultat:
222
Facette Requête
Le web service utilise la représentation ITMMASTER

Et l’entité (classe) ITMMASTER.
Test avec Soapui
25/02/2019 223
Facette Requête
Test avec Soapui
Saisissez l’URL suivante:

http://x3pu9trainvm/api1/x3/erp/X3PU9TRAIN_SEED_LOCALDOC/ITMMASTER?representation=
ITMMASTER.$query&count=20
Pour accéder au serveur Syracuse, vous devez donner le login

et le mot de passe utilisateur. Voir paramétrage basique de
l’authentification http.
Vous devez ajouter l’entête Accept

Sa valeur est:
text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,*/*;q=0.8
C’est la méthode HTTP GET.
25/02/2019 224
Facette Détails
Test en mode interactif

• Cliquez sur le numéro de commande
• Vous pouvez voir le détail d’une commande
Test avec le navigateur

• Saisissez dans votre navigateur:
http://x3pu9trainvm/api1/x3/erp/X3PU9TRAIN_SEED_LOCALDOC/ITMMASTER(‘APPLEWATCHSP
‘)?representation=ITMMASTER.$details
Résultat:
25/02/2019 225
Facette Détails
Test avec Soapui
http://x3pu9trainvm/api1/x3/erp/X3PU9TRAIN_SEED_LOCALDOC/ITMMASTER(‘APPLEWATCHSP’')?re
presentation=ITMMASTER.$details
25/02/2019 226
10 – Comment appeler un
Web Service externe
depuis X3
2/25/2019 227
Web services de test
Installation d'un Web Service dans un serveur PHP
• Accédez au fichier php-ws-x3_YYYYMMDD.zip

• Dézippez-le
• Copiez php-ws-x3 dans C:\Sage\wamp\www et renommez-le
sagex3-ws
• Connectez-vous à http://x3pu9trainvm:8125/sagex3-ws/web
• Vous pouvez tester ces web services REST.
- clicrdv
- creeraffaire
- eurostat
- hello
- stock
25/02/2019 229
Test du Web Service hello dans X3
Test du Web Service hello
Connectez-vous avec votre navigateur à
http://x3pu9trainvm:8125/sagex3-ws/web/hello/
Le résultat est : “Hello Everybody”
Connectez-vous à http://x3pu9trainvm:8125/sagex3-
ws/web/hello/?name=Olivier
Résultat: “Hello Olivier”
25/02/2019 231
Configuration et test de ces web services en X3
• Connexion à X3
• Administration > Web Services REST
• Nom du Web Service: “hello”
• L’url de Base comporte le vrai nom de la machine et le
dernier caractère doit être /.
• Vous pouvez tester avec le bouton ‘Test GET’
• OK.
25/02/2019 232
Appel de ces web services avec un script X3
http://.../hello
• Accédez au script ZCALLWSHELLO.src
• Exécutez ce script
O_HTTP_COD = func EXEC_REST_WS("hello", "GET", "", PARAMS_COD, PARAMS_VAL,

HEADERS_COD, HEADERS_VAL, "{}", 0, "", O_RESHEAD, O_RESBODY)
Infbox "STATUS_HTTP-->"-num$([L]O_HTTP_COD)
Infbox "BODY-->"-num$([L]O_RESBODY)
Résultats de ces web services:
25/02/2019 233
Appel de ces web services avec un script X3: suite
http://.../hello?name=Olivier
• Accédez au script ZCALLWSHELLO2.src
Résultats:
• Paramètres X3:
PARAMS_COD(1)= "name" : PARAMS_VAL(1)= '"Olivier"'
25/02/2019 234
Appel de ces web services avec un script X3: suite
http://.../hello?name=Olivier&formatreturn=JSON
• Accédez au script ZCALLWSHELLO3.src
Résultats:
• Paramètres X3:
RETURNS="message.name"
25/02/2019 235
Test du Web Service clicrdv dans X3
Test du Web Service clicrdv – Authentification http basique
• Connect to
http://x3pu9trainvm:8125/sagex3ws/web/clicrdv/api/v1/grou
ps/127723/
• Utilisateur : sage1
• Mot de passe : sage2
/
Résultat:
2/25/2019 237
Configuration et test de ces web services en X3
• Connexion à X3
• Administration > Web Services REST
• Nom du Web Service: « clicrdv »
• L’url de Base comporte le vrai nom de la
machine et le dernier caractère doit être /.
• Vous pouvez tester avec le bouton ‘Test GET’
• OK.
25/02/2019 238
Appelez le web service avec un script X3 - GET
http://.../clicrdv/api/v1/groups/127723/
• Accédez au script ZWSEXT_TST_CLICRDV_GET.src
Résultats des web services:
25/02/2019 239
Appelez le web service avec un script X3 - POST
http://.../clicrdv/api/v1/groups/127723/
• Accédez au script ZWSEXT_TST_CLICRDV_POST.src
Résultats des web services:
2/25/2019 240
Q&R
Posez toutes vos questions!
Conclusion
Dans ce workshop de “Niveau 1”:

• Vous avez reçu un outil PHP réutilisable
• Vous avez pris connaissance d’une
méthodologie pour être autonome dans
l’appel d’un WS X3 tel que:
- Sous-programme
- Objet
- X3 Version 7
• Vous avez travaillé sur un cas pratique de
WS X3 externe
25/02/2019 242
Thank you
© 2015, The Sage Group plc or its licensors. Sage, Sage logos, Sage product and service names mentioned herein are the trademarks of The Sage Group plc or its
licensors. All other trademarks are the property of their respective owners.
Annexes
2/25/2019 245
Ressources publiques GitHub
• https://github.com/orgs/Sage-ERP-X3
• sample-x3-ws-php-webportal : Exemple de cette documentation
• soap-tester-client : Ce répertoire contient du code .Net pour tester les Web Services Sage
ERP X3 Soap
2/25/2019 246
Comment appeler les web services X3
Voir dossier CALL_WS_X3\
• PHP : CALL_WS_X3\PHP\howto_PHP.txt
• C# : CALL_WS_X3\CSHARP\howto_CSHARP.txt
• JAVA : Appeler X3 web services REST & Soap
2/25/2019 247

Langue

S2B Training WS Level 1 Oma FR

Transféré par

Informations du document

Titre original

Copyright

Partager ce document

Partager ou intégrer le document

Options de partage

Avez-vous trouvé ce document utile ?

Ce contenu est-il inapproprié ?

Droits d'auteur :

S2B Training WS Level 1 Oma FR

Titre original :

Transféré par

Droits d'auteur :

Sage X3

• Rappel des prérequis

• Emploi du temps, pauses et règles

Stockable en mémoire cache

$4site = 'not yet'; // invalid; starts with a number

Lecture de la liste de clients (liste de gauche de Lecture d’une simple commande:

$order = new Order ();

La documentation est disponible soit en pdf ou directement en ligne.

• Ce portail est un portail de démo basé sur Wampserver.

• WampServer est un outil de développement

• Nouveau projet PHP

• Nom de projet sagex3

Architecture de la solution Sage X3

HTTP/HTTPS Web Client

Le Web Serveur Sage X3 publie des Web Services

X3 Serveur Web X3 Application

JSON WS Pool de Connexion

1. Action utilisateur : L’utilisateur X3 Application Server

Qu’est-ce que le pool de connexion?

Le pool de connexion est initialisé avec un nombre prédéfini de connexions.

> Démarre manuellement depuis la page administration

Un traitement niveau nœud qui gère les canaux

• Equilibrage de la Charge des Requêtes (Round Robin)

Web Service Publication Utility

L’utilitaire de publication (Développement / Processus / Processus/ Web Services)

Ouvrir Administration > Administration > Serveurs > Hôtes.

Basé sur le volume de données consommé.

• [0MB ; 1MB] → Vitesse normale

• Administration / Collaboration / Evénements de Notification

Dans l’aide en ligne :

• Publier des sous-programmes

• Le dictionnaire liste les arguments du sous-programme (détecté automatiquement à partir du

• Message d’information: Call MESSAGE(MESSAGE) From GESECRAN

Un unique sous-programme peut générer jusqu’à 50 messages.

Utilisation du programme encapsulant

• Le programme encapsulant contient du code de test permettant de s’assurer du bon

Vous pouvez utiliser l’outil open-source Soapui.

Obtenez le fichier de description wsdl dans X3

Obtenez le fichier de description wsdl dans X3

Obtenez le fichier de description wsdl dans X3

Créez un nouveau projet SOAP

Double-cliquez pour ouvrir cette requête

Modification de la balise xml en input

Obligatoire pour se connecter à X3.

Retour du web service

Statut NOK du Web Service

• Retour XML/JSON vide

• Les données sont rangées en paires nom/valeur

Les noms JSON nécessitent des guillemets doubles,

Valeurs JSON Objets JSON

<GRP ID="GRPn" DIM="1">

<TAB DIM=“1000“ ID=“GRP2“ SIZE=“5“>

Pour un input XML Pour un input JSON

Pour un output XML Pour un output JSON

-Les actions suivantes ne sont jamais exécutées en mode web service:

Le programme encapsulant est également créé, sous le nom suivant:

► Créez le web service WSORDER

Publiez the web service

Vous devez désélectionner des champs dans transaction de saisie WEB.

► Ouvrez le programme encapsulant et exécutez-le.

Résultat retourné par le web service

Cliquez sur Read.

Statut : 0 = NOK, =1=OK

Object Xml: the same description (in