API Web Service TéléAlerte
Transcription
API Web Service TéléAlerte
API Web Service TéléAlerte Version 1.2 (nov. 2013) Auteurs : Amos Faye, Stéphane Gibouin, Hennie Reyneke. Table des matières Table des matières ................................................................................................................................... 2 Introduction, démarche technique ........................................................................................................... 4 Prérequis : notion de scénario .................................................................................................................. 4 Définition des architectures et protocoles............................................................................................... 5 Moyen de sécurisation ............................................................................................................................. 5 Présentation : fonctionnalités du Web Service ........................................................................................ 6 Services ou classes de base : ................................................................................................................ 6 Types de données : ............................................................................................................................... 7 Types de données spécifiques.............................................................................................................. 7 Implémentation SOAP : ............................................................................................................................ 8 Authentification :.................................................................................................................................. 8 1. Récupération de la liste des sites auxquels l’identifiant API est associé. .............................. 8 2. Récupération de l’objet de session ...................................................................................... 10 Méthodes : ............................................................................................................................................. 12 Gestion des scénarios ............................................................................................................................. 14 GetScriptList ....................................................................................................................................... 14 Script ............................................................................................................................................... 14 Structure de la réponse : ........................................................................................................................ 15 GetScriptDetails .................................................................................................................................. 16 ScriptParameters ............................................................................................................................ 16 GetSubscribersDetails ........................................................................................................................ 18 Subscriber ....................................................................................................................................... 18 evaluateScript ..................................................................................................................................... 20 LoadIntroMsg ..................................................................................................................................... 21 LoadMainMsg ..................................................................................................................................... 21 LoadEndMsg ....................................................................................................................................... 21 UpdateWSColor .................................................................................................................................. 23 UpdateWSOrder ................................................................................................................................. 23 LaunchScript ....................................................................................................................................... 24 2 LaunchScriptParameters .................................................................................................................... 25 launchParams ................................................................................................................................. 25 fileUpload ........................................................................................................................................... 27 aSyncImportCSV ................................................................................................................................. 28 MapWrapper .................................................................................................................................. 28 syncImportCSV ................................................................................................................................... 30 ImportResults ................................................................................................................................. 30 getImportCSVStatus ........................................................................................................................... 32 getImportResults ................................................................................................................................ 33 getStats ............................................................................................................................................... 34 Media – Possible String values ....................................................................................................... 34 StatisticalResult .............................................................................................................................. 34 Script ............................................................................................................................................... 37 Gestion des envois directs...................................................................................................................... 38 SendSMS ............................................................................................................................................. 38 GetSMSStatus ..................................................................................................................................... 39 Kit de développement JAVA : ................................................................................................................. 40 Kit de développement PHP : .................................................................................................................. 40 Kit de développement C# : ..................................................................................................................... 40 Conclusion............................................................................................................................................... 40 3 Introduction, démarche technique La TéléAlerte de GEDICOM est un système de gestion complet et performant qui permet de gérer des campagnes téléphoniques, sms, fax, mail et pager. Gedicom a mis en place un Web Service permettant d’intégrer les fonctionnalités du système TéléAlerte à d’autres logiciels. Cette intégration est indépendante des langages de programmation utilisés côté client et serveur. Un ensemble de fonctionnalités de base sont présentes par défaut sur le système. L’équipe de développeur de Gedicom peut rapidement intégrer de nouvelles méthodes à la demande. Gedicom met à disposition un « package SDK PHP côté client» illustrant les intégrations décrites dans le présent document. Prérequis : notion de scénario Le scénario permet de prédéfinir un ensemble de comportements lors de l’envoi d’une campagne média. La campagne média regroupe un nombre défini de destinataires sur un ou plusieurs médias (Tél, Sms, Fax, etc…). Le scénario permet donc de s’abstraire d’un ensemble de comportements plus ou moins complexes (exemple : appel de tel groupe en priorité sur les portables et si absence envoi sur SMS etc…). Le principe étant de définir par avance (préprogrammer) les campagnes et ainsi de ne fournir que les informations nécessaires lors de l’envoi ; cela consolide le processus et permet de rapidement intégrer par API des situations qui peuvent être multiples et complexes. 4 Définition des architectures et protocoles Le protocole utilisé est SOAP. SOAP est un protocole bâti sur XML et qui permet la transmission de messages. Il définit les règles permettant de structurer les messages qui peuvent transiter par http entre le client et le serveur. Ces derniers ont pour contrainte d’être écrits dans des langages permettant de formuler et de comprendre les messages SOAP. Un fichier WSDL, disponible sur internet offre la description du Web Service. Afin de lancer les développements et pour simplifier il est possible aussi d’utiliser des méthodes http directes. Un document annexe peut être fournit si nécessaire mais Gedicom conseille vivement l’utilisation du protocole SOAP. Moyen de sécurisation Le service API SOAP TéléAlerte de Gedicom est protégé et seuls les utilisateurs autorisés peuvent l’utiliser. La sécurité est assurée par : - Un identifiant et un mot de passe API obligatoires - Transmission des données SSL Un échec de l’authentification interdit l’accès à l’API SOAP TéléAlerte. 5 Présentation : fonctionnalités du Web Service Fonctionnalités de base via le Web Service. Ces méthodes s’appuient sur une notion de scénario : - Session cryptée entre client et serveur - Récupération de la liste des scénarios définis au préalable sur le site classique de TéléAlerte - Récupération des informations générales et détaillées liés aux scénarios (id, description, messages textes et vocaux, groupes concernés, nombre de destinataires etc.) - Définition de l’ordre d’affichage des scénarios - Définition d’un code couleur pour chaque scénario - Téléchargement des messages vocaux liés aux scénarios - Evaluation du nombre de destinataires d’un scénario - Déclenchement d’un scénario Certaines fonctionnalités ont été intégrées afin de faciliter l’émission de SMS sans notion de scénario : - Envoi direct de SMS avec les options de bases. - Récupération de l’état d’envoi d’un SMS. Services ou classes de base : Les fonctionnalités de l’API SOAP de TéléAlerte sont mises en œuvre par deux services : Service Description SOAPSessionFactoryService Gère l’authentification. WSDL GedServerService Méthodes de récupération d’informations liées aux scénarios. Méthode de déclenchement des scénarios. WSDL 6 Types de données : L’API utilise les types de données primitives suivants : Valeur Détails Base64Binary Donnée binaire encodée en Base64 : format utilisé pour l’envoi des messages vocaux. String Chaîne de caractère. int Entier. Exemple : La méthode evaluateScript retourne le nombre de numéros de téléphones concernés par le scénario. boolean Valeurs possibles : true / false Types de données spécifiques En plus des données primitives, l’API définie ses propres types de données complexes : Valeur Détails script Type d’objet retourné par la méthode GetScriptList. Ce type d’objet contient les informations suivantes : Id, label, position du scénario, couleur du scénario. GetScriptList renvoie autant d’objets script qu’il y a de scénarios enregistrés. scriptParameters Type d’objet retourné par la méthode GetScriptDetails GetScriptDetails. Il contient des informations détaillées concernant un scénario : Id, catégorie, label, position, couleur, description, titre des messages vocaux, liste des groupes, texte des mails, des sms et des pagers. 7 Implémentation SOAP : Authentification : L’authentification est gérée par le service suivant : SOAPSessionFactoryService. Elle peut se faire en 2 étapes. 1. Récupération de la liste des sites auxquels l’identifiant API est associé. Cette étape est facultative pour la majorité de nos clients. Il faut en effet que le client dispose de plusieurs sites séparés (plusieurs contrats). Vous pouvez directement aller à l’étape 2. Structure de la requête : <soapenv:Envelope xmlns:soap="http://soap.gedicom.com/" xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"> <soapenv:Header> <wsse:Security soapenv:mustUnderstand="1" xmlns:wsse="http://docs.oasisopen.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd"> <wsu:Timestamp wsu:Id="Timestamp-9" xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis200401-wss-wssecurity-utility-1.0.xsd"> <wsu:Created>2013-11-15T16:07:18.576Z</wsu:Created> <wsu:Expires>2013-11-15T16:08:18.576Z</wsu:Expires> </wsu:Timestamp> </wsse:Security> </soapenv:Header> <soapenv:Body> <soap:PreLogin> <UserLog>api_username</UserLog> <Passwd>api_password</Passwd> </soap:PreLogin> </soapenv:Body> </soapenv:Envelope> Annotations de la requête : Ligne Commentaire 3 à 12 Le header doit obligatoirement contenir un Timestamp (Ligne 5 à 9). 13 à 18 Le body doit contenir les identifiants du WebService. Dans le corps de la requête, le client doit définir les éléments suivants : Elément Valeur Description <UserLog> api_username Votre identifiant API fournit par Gedicom sur demande. <Passwd> api_password Votre mot de passe API généré par Gedicom. 8 Structure de la réponse : <S:Envelope xmlns:S="http://schemas.xmlsoap.org/soap/envelope/" xmlns:wsse="http://docs.oasisopen.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd" xmlns:wsu="http://docs.oasisopen.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd" xmlns:xs="http://www.w3.org/2001/XMLSchema"> <S:Header> <wsse:Security S:mustUnderstand="1"> <wsu:Timestamp wsu:Id="_1" xmlns:ns15="http://schemas.xmlsoap.org/ws/2006/02/addressingidentity" xmlns:ns14="http://docs.oasisopen.org/ws-sx/ws-secureconversation/200512" xmlns:ns13="http://www.w3.org/2003/05/soap-envelope"> <wsu:Created>2013-11-16T09:58:19Z</wsu:Created> <wsu:Expires>2013-11-16T10:03:19Z</wsu:Expires> </wsu:Timestamp> </wsse:Security> </S:Header> <S:Body> <ns2:PreLoginResponse xmlns:ns2="http://soap.gedicom.com/" xmlns:ns3="http://www.w3.org/2005/08/addressing"> <return>[{"SiteLongName":"_Site de démonstration de Gedicom","SiteName":"GedDemo"}]</return> </ns2:PreLoginResponse> </S:Body> </S:Envelope> Annotations de la réponse : Ligne Commentaire 6 à 16 Le header contient toujours un élément <Timestamp>…</Timestamp> 17 Début du corps de la réponse 20 La balise <return> contient un tableau JSON ayant une entrée par site dont l’accès est autorisé pour ces identifiants (en général un seul site). 22 Fin du corps de la réponse 9 2. Récupération de l’objet de session Cette requête permet d’initier un partage de session entre les parties et ainsi il suffit de réinjecter l’identifiant unique à chaque requête afin d’éviter à redéposer systématiquement les identifiants et mots de passe. Le partage est d’autant plus sécurisé. L’objet renvoie aussi la classe permettant de déclencher les méthodes fournies par Gedicom (GedServer). Structure de la requête : <soapenv:Envelope xmlns:soap="http://soap.gedicom.com/" xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"> <soapenv:Header> <wsse:Security soapenv:mustUnderstand="1" xmlns:wsse="http://docs.oasisopen.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd"> <wsu:Timestamp wsu:Id="Timestamp-5" xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis200401-wss-wssecurity-utility-1.0.xsd"> <wsu:Created>2013-11-16T10:48:31.150Z</wsu:Created> <wsu:Expires>2013-11-16T10:49:31.150Z</wsu:Expires> </wsu:Timestamp> </wsse:Security> </soapenv:Header> <soapenv:Body> <soap:Login> <UserLog>api_username</UserLog> <Passwd>api_password</Passwd> <WebSite>APIDemo</WebSite> </soap:Login> </soapenv:Body> </soapenv:Envelope> La structure de la requête SOAP est la même que pour la requête de récupération des sites. Il faut ajouter le paramètre <WebSite>. Elément Valeur Description <WebSite> APIDemo Site choisi par l’utilisateur. Les noms des sites sont fournis par Gedicom, lors de la souscription à l’option API TéléAlerte. 10 Structure de la réponse : <S:Envelope xmlns:S="http://schemas.xmlsoap.org/soap/envelope/" xmlns:wsse="http://docs.oasisopen.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd" xmlns:wsu="http://docs.oasisopen.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd" xmlns:xs="http://www.w3.org/2001/XMLSchema"> <S:Header> <wsse:Security S:mustUnderstand="1"> <wsu:Timestamp wsu:Id="_1" xmlns:ns15="http://schemas.xmlsoap.org/ws/2006/02/addressingidentity" xmlns:ns14="http://docs.oasisopen.org/ws-sx/ws-secureconversation/200512" xmlns:ns13="http://www.w3.org/2003/05/soap-envelope"> <wsu:Created>2013-11-16T10:48:31Z</wsu:Created> <wsu:Expires>2013-11-16T10:53:31Z</wsu:Expires> </wsu:Timestamp> </wsse:Security> </S:Header> <S:Body> <ns2:LoginResponse xmlns:ns2="http://soap.gedicom.com/" xmlns:ns3="http://www.w3.org/2005/08/addressing"> <return> <ns3:Address>https://www.acces-gedicom.com:443/GedWSServer/GedServer</ns3:Address> <ns3:ReferenceParameters> <jaxws:objectId xmlns:jaxws="http://jax-ws.dev.java.net/xml/ns/" xmlns:wsa="http://www.w3.org/2005/08/addressing">object_id_value</jaxws:objectId> </ns3:ReferenceParameters> <ns3:Metadata wsdli:wsdlLocation="http://soap.gedicom.com/ https://www.accesgedicom.com:443/GedWSServer/GedServer?wsdl" xmlns:wsdli="http://www.w3.org/ns/wsdl-instance"> <wsam:InterfaceName xmlns:wsam="http://www.w3.org/2007/05/addressing/metadata" xmlns:jaxws="http://jax-ws.dev.java.net/xml/ns/" xmlns:wsa="http://www.w3.org/2005/08/addressing" xmlns:wsaw="http://www.w3.org/2006/05/addressing/wsdl" xmlns:wsns="http://soap.gedicom.com/">wsns:GedServer</wsam:InterfaceName> <wsam:ServiceName EndpointName="GedServerPort" xmlns:wsam="http://www.w3.org/2007/05/addressing/metadata" xmlns:jaxws="http://jaxws.dev.java.net/xml/ns/" xmlns:wsa="http://www.w3.org/2005/08/addressing" xmlns:wsaw="http://www.w3.org/2006/05/addressing/wsdl" xmlns:wsns="http://soap.gedicom.com/">wsns:GedServerService</wsam:ServiceName> </ns3:Metadata> </return> </ns2:LoginResponse> </S:Body> </S:Envelope> Annotations de la réponse SOAP : Ligne Description 6 à 16 Header. Chaque réponse SOAP contient un timestamp dans son header. 21 L’élément <Address> contient l’adresse du WebService permettant d’utiliser les fonctionnalités du système de TéléAlerte (GedServer). 24 L’élément <jaxws:objectId> contient un identifiant unique qui sera utilisé pour effectuer les requêtes pendant toute la session. Cet identifiant ne sera plus valide après déconnexion. 29 à 45 L’élément <ns3:metadata> contient des informations additionnelles notamment le nom de l’interface (GedServer) et le nom du service correspondant (GedServerService). 11 Méthodes : Voici la liste des méthodes pour le service GedServerService. Méthodes de gestion des scénarios : Méthode Description GetScriptList Renvoie la liste des scénarios enregistrés sur le site de TéléAlerte. GetScriptDetails Renvoie les informations détaillées d’un scénario à partir de son identifiant. GetSubscribersDetails Renvoie les informations détaillées d’un abonné à partir de son identifiant. evaluateScript Nombre de destinataires d’un scénario. LoadIntroMsg Télécharger le message d’introduction d’un scénario. LoadMainMsg Télécharger le message principal d’un scénario. LoadEndMsg Télécharger le message de fin d’un scénario. UpdateWSOrder Définir la position d’un scénario. UpdateWSColor Définir le code couleur d’un scénario. LaunchScript Déclencher un scénario. LaunchScriptParameters Déclencher un scénario avec possibilité de spécifier certains paramètres et/ou de fournir des valeurs aux groupes utilisés fileUpload Télécharger un fichier sur le serveur. Ce fichier pourra ensuite être utilisé pour importer son contenu dans le système. aSyncImportCSV Importation d’un fichier CSV de façon asynchrone syncImportCSV Importation d’un fichier CSV de façon synchrone getImportCSVStatus Obtenir le statut d'une importation CSV. getImportResults getImportResults Obtenir les résultats d'une importation CSV. getStats Obtenir les statistiques d'une campagne Logout Déconnecter la session. SensSMS Envoi d’un SMS simple GetSMSStatus Récupération de l’état d’un envoi de SMS simple 12 Corps En-tête Schéma de l’enveloppe d’une requête : Timestamp: <wsu:Timestamp> objectId : <jaxws:objectId> Eléments propres à chaque opération TéléAlerte En-tête générale d’une requête : <soapenv:Header> <wsse:Security soapenv:mustUnderstand="1" xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis200401-wss-wssecurity-secext-1.0.xsd" xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401wss-wssecurity-utility-1.0.xsd"> <wsu:Timestamp wsu:Id="TS-1"> <wsu:Created>2013-11-18T07:50:32.561Z</wsu:Created> <wsu:Expires>2013-11-18T07:51:32.561Z</wsu:Expires> </wsu:Timestamp> </wsse:Security> <jaxws:objectId xmlns:jaxws="http://jax-ws.dev.java.net/xml/ns/" xmlns:wsa="http://www.w3.org/2005/08/addressing">fe3cea34-d2fb-4802-8fcb-3c041029bc20</jaxws:objectId> </soapenv:Header> Annotations de la réponse SOAP : Ligne Description 6à9 Chaque en-tête de requête doit comporter un Timestamp. 11 Chaque en-tête doit également comporter un objectId. Il faut réutiliser l’objectId renvoyé à l’étape 2 de l’authentification. 13 Gestion des scénarios GetScriptList Returns all scenarios recorded in customer's website Parameters Type Description No parameters. Return Type Description ArrayList<Script> An ArrayList of type Script is returned. (See description below.) Methods Attributes Script int id; String label; int WSOrder; String WSColor; Getter- and setter methods for each attribute. Corps de la requête : <soapenv:Body> <soap:GetScriptList/> </soapenv:Body> 14 Structure de la réponse : <S:Envelope xmlns:S="http://schemas.xmlsoap.org/soap/envelope/" xmlns:wsse="http://docs.oasisopen.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd" xmlns:wsu="http://docs.oasisopen.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd" xmlns:xs="http://www.w3.org/2001/XMLSchema"> <S:Header> <wsse:Security S:mustUnderstand="1"> <wsu:Timestamp wsu:Id="_1" xmlns:ns15="http://schemas.xmlsoap.org/ws/2006/02/addressingidentity" xmlns:ns14="http://docs.oasisopen.org/ws-sx/ws-secureconversation/200512" xmlns:ns13="http://www.w3.org/2003/05/soap-envelope"> <wsu:Created>2013-11-18T07:50:36Z</wsu:Created> <wsu:Expires>2013-11-18T07:55:36Z</wsu:Expires> </wsu:Timestamp> </wsse:Security> </S:Header> <S:Body> <ns2:GetScriptListResponse xmlns:ns2="http://soap.gedicom.com/"> <return> <id>168</id> <label>Test_1 API TeleAlerte</label> <WSColor>b</WSColor> <WSOrder>0</WSOrder> </return> </ns2:GetScriptListResponse> </S:Body> </S:Envelope> Annotations de la réponse : Ligne Description 8 à 14 Chaque réponse contient un Timestamp 20 L’élément <id> contient l’id du scénario en question 21 L’élément <label> contient le nom donné au scénario 22 L’élément <WSColor> contient un code couleur affecté au scénario. Cet élément peut également être défini afin d’être adapté aux besoins du client. 23 L’élément <WSOrder> contient la position du scénario. Cette position peut également être définie. 15 GetScriptDetails Returns the parameters for a scenario. Parameters Type Description ScriptId String The ID of the scenario. Return Type Description ScriptParameters ScriptParameters object is returned – see description below. Methods Attributes ScriptParameters int id; String label; String desc; String GrpList; String IntoMsgLabel; String MainMsgLabel; String EndMsgLabel; int type; int cat; int WSOrder; String WSColor; String SMSTxt; String MailSub; String MailTxt; String PagerTxt; Getter- and setter methods for each attribute. Corps de la requête : <soapenv:Body> <soap:GetScriptDetails> <ScriptId>168</ScriptId> </soap:GetScriptDetails> </soapenv:Body> 16 Corps de la réponse : <S:Body> <ns2:GetScriptDetailsResponse xmlns:ns2="http://soap.gedicom.com/"> <return> <cat>0</cat> <desc>Test démo</desc> <endMsgLabel>null</endMsgLabel> <grpList><![CDATA[<div><input type="hidden" name="OpChk" value="90"><input type="hidden" name="Op90" value="0"><b>90</b> - Test CCH /Gedicom</div>]]></grpList> <id>168</id> <introMsgLabel>null</introMsgLabel> <mailSub/> <mailTxt/> <mainMsgLabel>Test CCH2</mainMsgLabel> <pagerTxt/> <smsTxt>Campagne de test de CCH pour démo Gedicom</smsTxt> <type>0</type> <WSColor>b</WSColor> <WSOrder>0</WSOrder> <label>Test CCH Démo Gedicom</label> </return> </ns2:GetScriptDetailsResponse> </S:Body> Eléments de la réponse : Elément Description <cat> Catégorie du message. <desc> Description du message. <endMsgLabel> Libellé du message de fin. ‘null’ si aucun message de fin n’est enregistré. <grpList> Liste des groupes associés au scénario <introMsgLabel> Libellé du message d’introduction. ‘null’ si aucun message d’introduction n’est enregistré. <mailSub> Sujet du mail associé au scénario. <mailTxt> Texte du mail. <mainMsgLabel> Libellé du message de fin. ‘null’ si aucun message principal n’est enregistré. <pagerTxt> Texte du message pager. <smsTxt> Texte du sms. <type> Type du scénario. 17 GetSubscribersDetails Retourne les informations de la fiche d’un abonné (sans les données étendues). Parameters Type Description PhoneId String Référence de l’abonné. Return Type Description Subscriber Retourne les informations de la fiche d’un abonné (voir ci-dessous) Methodes Attributes Subscriber String PhoneId; String TypeAbo; String Civility; String Name; String FullAddress; String PostalCode; String City; String EmailAddress; String PhoneId2; String PhoneId3; String PhoneId4; String PhoneId5; String PhoneId6; String PhoneId7; String SMS; String Fax; String BirthDate; String Floor; String NbOfPeople; String Launguage; String FreeZone1; String FreeZone2; String FreeZone3; String GPSCoords; String CountryCode; Getter- and setter methods for each attribute. Corps de la requête : 18 <soapenv:Body> <soap:getSubscribersDetails> <PhoneId>0123456789</PhoneId> </soap:getSubscribersDetails> </soapenv:Body> Corps de la réponse : <S:Body> <ns2:getSubscribersDetailsResponse xmlns:ns2="http://soap.gedicom.com/"> <return> <birthDate/> <city/> <civility/> <countryCode/> <emailAddress/> <fax/> <floor>0</floor> <freeZone1/> <freeZone2/> <freeZone3/> <fullAddress>31 Rue de la Paix</fullAddress> <GPSCoordinates/> <language/> <name>Toto</name> <nbOfPeople>1</nbOfPeople> <phoneId>0123456789</phoneId> <phoneId2/> <phoneId3/> <phoneId4/> <phoneId5/> <phoneId6/> <phoneId7/> <postalCode/> <SMS/> <typeAbo/> </return> </ns2:getSubscribersDetailsResponse> </S:Body> 19 evaluateScript Evalue le nombre de destinataires du scenario. Parameters Type Description ScriptId String Identifiant (numéro) du scenario. Return Type Description int Nombre de destinataires. Corps de la requête : <soapenv:Body> <soap:evaluateScript> <ScriptId>168</ScriptId> </soap:evaluateScript> </soapenv:Body> Corps de la réponse : <S:Body> <ns2:evaluateScriptResponse xmlns:ns2="http://soap.gedicom.com/"> <return>1</return> </ns2:evaluateScriptResponse> </S:Body> 20 LoadIntroMsg Permet de télécharger le message d’introduction du dernier script chargé (GetScriptDetails). Parameters Type Description No parameters. Return Type Description DataHandler Returns a DataHandler object. LoadMainMsg Permet de télécharger le message principal du dernier script chargé (GetScriptDetails). Parameters Type Description No parameters. Return Type Description DataHandler Returns a DataHandler object. LoadEndMsg Permet de télécharger le message de fin du dernier script chargé (GetScriptDetails). Parameters Type Description No parameters. Return Type Description DataHandler Returns a DataHandler object. Corps de la requête : <soapenv:Body> <soap:Load...Msg/> </soapenv:Body> Corps de la réponse : 21 <S:Body> <ns2:Load...MsgResponse xmlns:ns2="http://soap.gedicom.com/"> <return>base64binary</return> </ns2:Load...MsgResponse> </S:Body> La réponse comporte des données binaires encodées au format base64 correspondant au message vocal demandé. 22 UpdateWSColor Updates the scenario colour. Parameters Type Description ScriptId String The ID of the scenario. WSColor String The colour scheme for the scenario. Return Type Description boolean True when successfully executed, otherwise false. UpdateWSOrder Updates the scenario position. Parameters Type Description ScriptId String The ID of the scenario. WSOrder String The scenario position. Return Type Description boolean True when successfully executed, otherwise false. Corps de la requête : <soapenv:Body> <soap:UpdateWS...> <ScriptId>168</ScriptId> <WSColor>d</WSColor> </soap:UpdateWS...> </soapenv:Body> Corps de la réponse : <S:Body> <ns2:UpdateWS...Response xmlns:ns2="http://soap.gedicom.com/"> <return>true</return> </ns2:UpdateWS...Response> </S:Body> Le serveur retourne la valeur « true » si la mise à jour s’est bien déroulée (sinon « false »). 23 LaunchScript Lance une campagne à partir d’un scénario. Parameters Type Description ScriptId String Identifiant du scenario. Return Type Description int Numéro de la champagne créée (-1 si erreur) Corps de la requête : <soapenv:Body> <soap:LaunchScript> <ScriptId>168</ScriptId> </soap:LaunchScript> </soapenv:Body> Corps de la réponse : <S:Body> <ns2:LaunchScriptResponse xmlns:ns2="http://soap.gedicom.com/"> <return>18000</return> </ns2:LaunchScriptResponse> </S:Body> 24 LaunchScriptParameters Lance une campagne à partir d’un scénario. Cette méthode permet de définir les valeurs de certains paramètres du scénario et de fournir (le cas échéant) des valeurs aux groupes dynamiques variables ciblés par ce scénario. Parameters Type Description ScriptId String Identifiant du scenario (numéro de scenario) launchParams[] launchParam Table d’objets launchParams contenant les paramètres que le scénario devra prendre en compte pour lancer la campagne. String values[] Table des valeurs attendues par le(s) groupe(s) dynamique(s) variable(s) du scénario Return Type Description int Identifiant de la campagne créée (-1 si erreur) Methodes Attributes launchParams String FieldName; String Value; String ExtField; String ExtValue; Getter- and setter methods for each attribute. Corps de la requête : <soapenv:Body> <soap:LaunchScriptParameters> <ScriptId>197</ScriptId> <values>17001</values> </soap:LaunchScriptParameters> </soapenv:Body> Corps de la réponse : 25 <S:Body> <ns2:LaunchScriptParametersResponse xmlns:ns2="http://soap.gedicom.com/"> <return>38451</return> </ns2:LaunchScriptParametersResponse> </S:Body> Le serveur retourne la valeur de la campagne créée (ici 38451). Cet identifiant pourra ensuite, par exemple, être utilisé pour obtenir des statistiques sur cette campagne. 26 fileUpload Méthode permettant de charger un fichier sur le serveur. Le fichier chargé pourra ensuite être utilisé par le système, par exemple pour importer son contenu/ Parameters Type Description fileName String Nom complet (absolu) du fichier à charger (sur votre système) fileData DataHandler Contenu du fichier Return Type Description String Nom du fichier chargé sur le serveur Corps de la requête : <soapenv:Body> <soap:fileUpload> <fileName>C:\Test\test.csv</fileName> <fileData>cid:652891985198</fileData> </soap:fileUpload> </soapenv:Body> Corps de la réponse : <S:Body> <ns2:fileUploadResponse xmlns:ns2="http://soap.gedicom.com/"> <return>test_c100f9ece9.csv</return> </ns2:fileUploadResponse> </S:Body> Le nom du fichier serveur (ici test_c100f9ece9.csv) servira de référence pour importer son contenu (voir méthodes aSyncImportCSV et syncImportCSV). 27 aSyncImportCSV Importer un fichier CSV dans le système de façon asynchrone. Parameters Type Description fileReference String Référence du fichier sur le serveur associations MapWrapper MapWrapper contenant les associations entre noms de colonnes du fichier et nom de champs (voir Annexe 1). Key=nom de colonne, Value=nom de champs. options MapWrapper MapWrapper contenant les options d’importation (voir Annexe 1). Return Type Description int Référence (numéro) de l’opération d’importation. Methodes Members MapWrapper Map<String, String> map; Map getMap() setMap(Map map) MapWrapper getWrapperFromMap(Map<String, String> map) Corps de la requête : <soapenv:Body> <soap:asyncImportCSV> <fileReference>test.csv</fileReference> <associations> <map> <entry key="col1">PHONE1</entry> <entry key="col2">FIRSTNAME</entry> <entry key="col3">ADDRESS</entry> </map> </associations> <options> </options> </soap:asyncImportCSV> </soapenv:Body> 28 Corps de la réponse : <S:Body> <ns2:asyncImportCSVResponse xmlns:ns2="http://soap.gedicom.com/"> <return>412</return> </ns2:asyncImportCSVResponse> </S:Body> 29 syncImportCSV Importer un fichier CSV dans le système de façon synchrone. Parameters Type Description fileReference String Référence du fichier sur le serveur associations MapWrapper MapWrapper contenant les associations entre noms de colonnes du fichier et nom de champs (voir Annexe 1). Key=nom de colonne, Value=nom de champs. options MapWrapper MapWrapper contenant les options d’importation (voir Annexe 1). Return Type Description ImportResults Retourne un objet de type ImportResults (voir ci-dessous) contenant les résultats de l’importation. Methodes Attributes ImportResults int total; int updated; int notUpdated; int added; int deletedFromSys; int newUsers; int deleted; int doubled; int grpId; int emptyLines; int ignored; boolean importTxt; String selectedFields; int grpOpion; String SQLError; Getter- and setter methods for each attribute. Corps de la requête : 30 <soapenv:Body> <soap:syncImportCSV> <fileReference>test.csv</fileReference> <associations> <map> <entry key="col1">PHONE1</entry> <entry key="col2">FIRSTNAME</entry> <entry key="col3">ADDRESS</entry> </map> </associations> <options> </options> </soap:syncImportCSV> </soapenv:Body> Corps de la réponse : <S:Body> <ns2:syncImportCSVResponse xmlns:ns2="http://soap.gedicom.com/"> <return> <added>0</added> <deleted>0</deleted> <deletedFromSys>0</deletedFromSys> <doubled>0</doubled> <emptyLines>0</emptyLines> <grpId>0</grpId> <grpOption>0</grpOption> <ignored>0</ignored> <importTxt>false</importTxt> <newUsers>0</newUsers> <notUpdated>0</notUpdated> <total>1</total> <updated>1</updated> </return> </ns2:syncImportCSVResponse> </S:Body> 31 getImportCSVStatus Retourne le statut de l’opération d’importation importationId. Parameters Type Description importationId int Référence (numéro) de l’opération d’importation. Return Type Description String Retourne le statut de l’opération d’importation. "Process launched but not started" = pas encore démarée "Processing" = en cours "Done" = terminée avec succès "Error" = en erreur "Operation does not exist" = opération inexistante Corps de la requête : <soapenv:Body> <soap:getImportCSVStatus> <importationId>413</importationId> </soap:getImportCSVStatus> </soapenv:Body> Corps de la réponse : <S:Body> <ns2:getImportCSVStatusResponse xmlns:ns2="http://soap.gedicom.com/"> <return>Done</return> </ns2:getImportCSVStatusResponse> </S:Body> 32 getImportResults Retourne le résultat d’une operation d’importation. Parameters Type Description importationId int Référence (numéro) de l’opération d’importation. Return Type Description ImportResults Retourne un objet de type ImportResults (voir ci-dessous) contenant les résultats de l’importation. Corps de la requête : <soapenv:Body> <soap:getImportResults> <importationId>413</importationId> </soap:getImportResults> </soapenv:Body> Corps de la réponse : <S:Body> <ns2:getImportResultsResponse xmlns:ns2="http://soap.gedicom.com/"> <return> <added>0</added> <deleted>0</deleted> <deletedFromSys>0</deletedFromSys> <doubled>0</doubled> <emptyLines>0</emptyLines> <grpId>0</grpId> <grpOption>0</grpOption> <ignored>0</ignored> <importTxt>false</importTxt> <newUsers>0</newUsers> <notUpdated>0</notUpdated> <total>1</total> <updated>1</updated> </return> </ns2:getImportResultsResponse> </S:Body> 33 getStats Retourne la liste des statistiques générales pour la campagne nID et le media media. Parameters Type Description nID int Identifiant de la campagne. media String Identifiant du media (voir liste ci-dessous). Return Type Description List<StatisticalResult> Retourne une liste des statistiques (objet StatisticalResult, voir description ci-dessous). Possible Values Media – Possible String values String SUBSCRIBERS; String CALL; String GSM; String SMS; String FAX; String MAIL; String PAGER; String ANSWERS; Attributes int rowNum; int stat; Methodes StatisticalResult Getter- and setter methods for each attribute. Corps de la requête : 34 <soapenv:Body> <soap:getStats> <nID>413</nID> <media>MAIL</media> </soap:getStats> </soapenv:Body> Corps de la réponse : <S:Body> <ns2:getStatsResponse xmlns:ns2="http://soap.gedicom.com/"/> </S:Body> 35 Logout Ferme la connexion (session) au web-service. Parameters Type Description Aucun paramètre. Return Type Description Pas de retour. Corps de la requête : <soapenv:Body> <soap:Logout/> </soapenv:Body> Corps de la réponse : <S:Body> <ns2:LogoutResponse xmlns:ns2="http://soap.gedicom.com/"/> </S:Body> Après cette opération, l’objectid utilisé dans toutes les requêtes expire. Il faut renouveler le processus d’authentification. GetScriptList Retourne tous les scenarios disponibles Parameters Type Description Aucun paramètre. Return Type Description ArrayList<Script> Liste des scenarios disponibles. Voir description de l’objet Script cidessous. 36 Methods Attributes Script int id; String label; int WSOrder; String WSColor; Getter- and setter methods for each attribute. 37 Gestion des envois directs SendSMS Send an SMS. Parameters Type Description Phone String Numéro de mobile de destination SmsTxt String Texte SMS Return Type Description int Référence de l’envoi Corps de la requête : <soapenv:Body> <soap:sendSMS> <Phone>0601020304</Phone> <SmsTxt>Bonjour, information par SMS.</SmsTxt> </soap: sendSMS > </soapenv:Body> Corps de la réponse : <S:Body> <ns2:SendSMSResponse xmlns:ns2="http://soap.gedicom.com/"> <return>123456</return> </ns2: SendSMSResponse > </S:Body> Eléments de la réponse : Elément Description <return> Identifiant unique pour cet envoi. Référence à rappeler lors de la scrutation des statistiques (=> StatRef de la méthode suivante). 38 GetSMSStatus Retourne le statut d’un SMS. Parameters Type Description StatRef String Référence de l’envoi. Return Type Description int Statut de l’envoi du SMS (voir plus bas pour plus de détails). Corps de la requête : <soapenv:Body> <soap:GetSMSStatus> <StatRef>123456</StatRef> </soap: GetSMSStatus > </soapenv:Body> Corps de la réponse : <S:Body> <ns2:GetSMSStatusResponse xmlns:ns2="http://soap.gedicom.com/"> <return>0</return> </ns2: GetSMSStatus > </S:Body> Eléments de la réponse : Elément Description <return> Etat (statut) des SMS : -1 : En attente forcée par le système Gedicom (cas ne devant pas apparaître) 0 : SMS inscrit sur les bases, avant traitement par le moteur d’envoi 7 : Mauvais numéro 15 : Erreur SMS 18 : Envoyé à l’opérateur 22 : SMS reçu 39 Kit de développement JAVA : Un kit de développement de l’API TéléAlerte est fourni à la demande. Il comporte les sources nécessaires à la création d’un client java ainsi qu’un exemple d’utilisation. Kit de développement PHP : Un kit de développement PHP est fourni à la demande. L’outil utilisé pour la création du client WebService est nusoap. Un exemple d’utilisation est également fourni dans un fichier sample.php. Kit de développement C# : Un document explicatif, guidant la génération d’une application cliente est téléchargeable sur notre site. Conclusion Le web service de Gedicom est une solution simple, sécurisée et fonctionnelle qui facilite le déclenchement des scénarios définis au préalable sur le site de TéléAlerte sur différents canaux (téléphone, sms, email, fax, pager). Il permet aussi l’envoi « à la volée » d’un certain nombre de média, notamment le SMS. L’évolutivité de cet outil permet à Gedicom de fournir un service qui correspond aux contraintes de l’ensemble des cahiers des charges pour les web services. 40