Pour comprendre le fonctionnement des services web avec Divalto, voici un schéma illustré avec des notions simples sur le traitement d'un courrier papier.
Courrier métier
- Le demandeur rédige un message pour le service métier auquel il s'adresse, par exemple une lettre de réclamation adressée au service client de l'entreprise.
- Ce message, portant un objet, est mis sous enveloppe et placé dans un colis de transport.
- Le colis de transport va utiliser un moyen de transport pour entrer dans l'entreprise identifiée par son adresse, par exemple Cedex 1.
- L'enveloppe est sortie de son colis pour être remis au service courrier de l'entreprise.
- Le service courrier ouvre l'enveloppe, extrait l'objet et dépose le message au service métier selon l'objet de la lettre.
- Le service métier exploite le message et effectue son traitement, et apporte une réponse au demandeur.
Formulaire de demande de données
- Le demandeur remplit un formulaire de demande de données
- Le formulaire va utiliser un moyen de transport pour entrer dans l'entreprise par un accès dédié RECORSQL
- Le service RECORDSQL recherche les données, et renvoie les données au demandeur
et son parallèle sur le traitement d'un appel de service web
Service web métier
- Le demandeur construit un message pour le service web métier auquel il s'adresse, par exemple un message de création d'évènement CRM.
- Ce message, portant une action, est enveloppé selon le protocole de transport cible par des balises XML ou JSON, et placé dans un flux complet XML ou JSON.
- Le flux complet XML ou JSON va utiliser un protocole de transport via l'URL du serveur web pour entrer l'action de service web Harmony.
- L'enveloppe XML ou JSON est sortie du flux complet pour être remis à l'action de service web, par exemple SYNCHRO_INFINITY_AGILEO.
- L'action de service web extrait de l'enveloppe XML ou JSON l'action métier, et dépose le message au traitement Diva métier selon l'action.
- Le traitement Diva métier exploite le message et effectue son traitement, et apporte une réponse au demandeur (format XML ou JSON selon le service métier).
Service API Recordsql
- Le demandeur remplit une de demande de données au format JSON
- Le flux JSON va utiliser un protocole de transport REST via l'URL du serveur API Recordsql pour un traitement natif
- L'API RECORDSQL recherche les données en exécutant une requête SQL , et renvoie les données au demandeur (format JSON)
Il faut bien distinguer les 5 éléments qui entrent dans un dialogue service web ou API.
1. Le MESSAGE
Le MESSAGE doit être dans le format attendu pour l'exécution d'une ACTION METIER.
C'est l'écriture du traitement Diva (qui va gérer l'action métier) qui détermine
- le contenu possible de ce message : il est donc spécifique a chaque action métier, par exemple : interroger un stock, consulter des droits, déposer un dataset.
- le format : par exemple : balises HMP, texte XML, texte JSON
Pour connaître les messages, il faut consulter la documentation concernant les actions métier
Action et Param
Tous les messages vers Divalto ont nécessairement 2 parties:
- ACTION, ou action de service web : sert uniquement au Service Web Harmony pour l'orientation du message au bon traitement Diva
- PARAM : ce sont toutes les données pour le traitement de l'ACTION METIER
2. Le MODE DE TRANSPORT
Le MODE DE TRANSPORT impose une technologie aux échanges, notamment tout ce qui enveloppe le message (authentification, format, styles, schémas)
Harmony permet l'utilisation de deux technologies
- mode de transport SOAP qui utilise un format XML
- mode de transport REST qui utilise un format JSON
Il est recommandé d'utiliser le mode de transport REST qui permet une authentification de l'appelant.
Cette authentification est une action préalable a l'appel du service web afin d'obtenir un TOKEN joint à l'appel
3. Le SERVICE IIS
Le SERVICE IIS est le composant qui permet d'exposer des services web sur internet ou sur le réseau de l'entreprise.
Le service IIS permet a un appelant d'avoir une URL (adresse internet sous la forme HTTP://monAdresse/serviceIIS) qui lui permet de faire une demande de service web ou API.
Harmony fournit deux service IIS
- un SOAP, sous la forme http://localhost:8080/WebServiceDiva/webservicediva.asmx
- un REST, sous la forme http://localhost:8080/DhsDivaltoServiceDivaApiRest/api/v1/WebService/
Chacun de ces services a son propre paramétrage, et nécessite une installation préalable.
Le SERVICE IIS REST propose plus de possibilités de paramétrage (cache, durée du token) que SOAP
Sur un poste Windows, Internet Information Service est une fonctionnalité a activer
4. Le SERVICE WEB HARMONY - Action de service web (pour un service métier uniquement)
Le SERVICE WEB HARMONY, ou action de service web, fait l'intermédiaire entre le SERVICE IIS et le traitement Diva indiqué dans le paramétrage harmony des actions de services web.
Il sert uniquement a aiguiller le MESSAGE de l'appelant vers le traitement Diva en fournissant un contexte d'exécution (droits ERP et implicites).
Ce service web va donc utiliser la partie ACTION du MESSAGE pour déterminer le traitement de l'action
Divalto propose de configurer deux services web harmony afin de bénéficier des services web métiers standard fournis avec l'ERP.
- Le service web harmony SYNCHRO_INFINITY_AGILEO, qui fait appel au traitement générique A5PPSWAGIL.DHOP, et qui a été développé historiquement en mode SOAP
- Le service web harmony WEB_SERVICE_INFINITY, qui qui fait appel au traitement générique A5PPSWINFINITY.DHOP, et qui a été développé en mode REST
Nommage
Le respect des noms des services web Divalto standards (SYNCHRO_INFINITY_AGILEO et WEB_SERVICE_INFINITY) permet de les mettre en oeuvre plus facilement, car les interactions au sein de Divalto Infinity ou avec Weavy ou Agiléo sont prévues pour passer par défaut par ces noms de services.
Cependant, il est possible de leur attribuer un autre nom, tout en conservant le traitement générique (.DHOP) qui est associé.
Pour des raisons de cohérence :
- les services web métier passant par le service web standard SYNCHRO_INFINITY_AGILEO (qui a été fait pour du mode de transport SOAP) ont été développés pour recevoir des messages au format XML.
- les services web métier passant par le service web standard WEB_SERVICE_INFINITY (qui a été fait pour du mode de transport REST) ont été développés pour recevoir des messages au format JSON.
Les combinaisons sont possibles !
- on peut appeler un service web métier qui attend un message XML depuis un transport REST
- on peut appeler un service web métier qui attend un message JSON depuis un transport SOAP
Recommandation
Pour des raisons de sécurité, depuis Infinity 10.5 et le Runtime Harmony 406, il est recommandé d'utiliser le mode de transport REST qui permet une authentification.
Les anciens services web métier, développés pour recevoir un message au format XML, peuvent être appelés dans ce mode REST a condition que le message reste sous format XML/HMP et que l'appelant gère l'authentification
5. Le TRAITEMENT DIVA / ACTION METIER
5.1 Pour un service métier
L'ACTION METIER est réalisée par un TRAITEMENT DIVA qui va exploiter la partie PARAM du MESSAGE.
Le traitement exploite donc directement le PARAM reçu pour effectuer le traitement métier demandé par l'appelant.
Services métier standards
Les traitements génériques (A5PPSWAGIL.DHOP et A5PPSWINFINITY.DHOP) associés aux services métiers standards fournis avec Infinity ont la particularité d'être des points d'entrée uniques.
Ils bénéficient donc d'un système de routage pour re-orienter vers un module Diva spécialisé dans un métier (par exemple en gestion commerciale, en paie,...)
Ce routage se fait par la balise <ACTION> qui est contenue dans la partie PARAM du message, par exemple <ACTION>interroger_stock
5.1 Pour un service API Recordsql
Le traitement est effectué directement par l'API RecordSql, avec exécution d'une requête SELECT dans la base de donneés.
Cette requête utilise la couche d'accès aux données que sont les RecordSql Diva.