L'ensemble des méthodes de l'API sont exposées sous forme de service Web. Ainsi, il est possible de piloter l'intégralité des fonctionnalités d'Adobe Campaign au travers d'appels SOAP qui sont le point d'entrée natif du serveur d'application Adobe Campaign. La console Adobe Campaign elle-même n'utilise que des appels SOAP.
Les services Web permettent de créer, depuis un système tiers, de multiples applications :
La définition des services Web implémentés sur le serveur applicatif Adobe Campaign est disponible à partir des schémas de données.
Un service Web est décrit dans la grammaire des schémas de données et est disponible à partir de l'élément <methods>
.
<methods>
<method name="GenerateForm" static="true">
<help>Generates the form in Mail or Web mode</help>
<parameters>
<param name="formName" type="string" desc="Name of form"/>
<param name="mailMode" type="boolean" desc="Generate a form of type Mail"/>
<param name="result" type="string" inout="out" desc="Result "/>
</parameters>
</method>
</methods>
Nous avons ici un exemple de définition de la méthode de nom GenerateForm.
La description du service commence par l'élément <method>
. La liste des paramètres de la méthode est complétée à partir de l'élément <parameters>
. Chaque paramètre est spécifié par un nom, un type (booléen, chaîne, DOMElement, etc.) et une description. L'attribut "inout" avec la valeur "out" permet de spécifier que le paramètre "result" est obtenu en sortie de l'appel SOAP.
La présence de l'attribut "static" (avec la valeur "true") décrit cette méthode comme statique, ce qui signifie que tous les paramètres de la méthode doivent être déclarés.
Une méthode de type "const" possède implicitement en entrée un document XML au format de son schéma associé.
Une description complète de l'élément <method>
d'un schéma Adobe Campaign figure dans la section Méthode du chapitre « Référence des schémas ».
Exemple de la méthode "ExecuteQuery" de type "const" à partir du schéma "xtk:queryDef" :
<method name="ExecuteQuery" const="true">
<help>Retrieve data from a query</help>
<parameters>
<param desc="Output xml document" name="output" type="DOMDocument" inout="out"/>
</parameters>
</method>
Le paramètre en entrée de cette méthode est un document XML au format du schéma "xtk:queryDef".
Un fichier WSDL (Web Service Description Library) est disponible pour chaque service. Ce fichier écrit en XML décrit le service dans un méta-langage, il précise les méthodes disponibles, les paramètres et le serveur à contacter pour exécuter le service.
Pour générer un fichier WSDL vous devez, à partir d'un navigateur Web, saisir l'URL suivante :
https://<server>
/nl/jsp/schemawsdl.jsp?schema=<schema>
Avec :
<server>
: le serveur applicatif Adobe Campaign (nlserver web)<schema>
: la clé d'identification du schéma (namespace:nom_du_schéma)On génère le fichier WSDL à partir de l’URL :
https://localhost/nl/jsp/schemawsdl.jsp?schema=xtk:queryDef
Une description WSDL définit d’abord les types utilisés pour former des messages, associés dans des « ports », reliés à un protocole par des « liaisons » formant des Services Web.
Les définitions de type reposent sur des schémas XML. Dans notre exemple, la méthode "ExecuteQuery" utilise comme paramètres une chaîne "s:string" et un document XML (<s:complextype>
). La valeur renvoyée par la méthode ("ExecuteQueryResponse") est un document XML ( <s:complextype>
).
<types>
<s:schema elementFormDefault="qualified" targetNamespace="urn:xtk:queryDef">
<s:element name="ExecuteQuery">
<s:complexType>
<s:sequence>
<s:element maxOccurs="1" minOccurs="1" name="sessiontoken" type="s:string"/>
<s:element maxOccurs="1" minOccurs="1" name="entity">
<s:complexType>
<s:sequence>
<s:any/>
</s:sequence>
</s:complexType>
</s:element>
</s:sequence>
</s:complexType>
</s:element>
<s:element name="ExecuteQueryResponse">
<s:complexType>
<s:sequence>
<s:element maxOccurs="1" minOccurs="1" name="pdomOutput">
<s:complexType mixed="true">
<s:sequence>
<s:any/>
</s:sequence>
</s:complexType>
</s:element>
</s:sequence>
</s:complexType>
</s:element>
Le <message>
décrit les noms et les types d'un ensemble de champs à envoyer. La méthode utilise deux messages à transmettre en tant que paramètre ("ExecuteQueryIn") et la valeur renvoyée ("ExecuteQueryOut").
<message name="ExecuteQueryIn">
<part element="tns:ExecuteQuery" name="parameters"/>
</message>
<message name="ExecuteQueryOut">
<part element="tns:ExecuteQueryResponse" name="parameters"/>
</message>
La partie <porttype>
associe les messages sur l'opération "ExecuteQuery" déclenchée par la requête ("input") générant une réponse ("output").
<portType name="queryDefMethodsSoap">
<operation name="ExecuteQuery">
<input message="tns:ExecuteQueryIn"/>
<output message="tns:ExecuteQueryOut"/>
</operation>
</portType>
La partie <binding>
spécifie le protocole de communication SOAP ( <soap:binding>
), le transport de données en HTTP (valeur de l'attribut "transport") et le format de données pour l'opération "ExecuteQuery". Le corps de l'enveloppe SOAP contient les segments de message, directement, sans transformation.
<binding name="queryDefMethodsSoap" type="tns:queryDefMethodsSoap">
<soap:binding style="document" transport="http://schemas.xmlsoap.org/soap/http"/>
<operation name="ExecuteQuery">
<soap:operation soapAction="xtk:queryDef#ExecuteQuery" style="document"/>
<input>
<soap:body encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" namespace="urn:xtk:queryDef" use="literal"/>
</input>
<output>
<soap:body encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" namespace="urn:xtk:queryDef" use="literal"/>
</output>
</operation>
</binding>
La partie <service>
décrit le service "XtkQueryDef" avec son URI sur l'URL du serveur applicatif Adobe Campaign.
<service name="XtkQueryDef">
<port binding="tns:queryDefMethodsSoap" name="queryDefMethodsSoap">
<soap:address location="https://localhost/nl/jsp/soaprouter.jsp"/>
</port>
</service>
Adobe Campaign a renforcé la sécurité des mécanismes d'authentification en introduisant les zones de sécurité et paramètres de gestion des sessions.
Deux modes d'authentification sont disponibles :
ou
Le jeton de session possède les caractéristiques suivantes :
une durée de vie de X heures (la durée de vie est paramétrable dans le fichier 'serverConf.xml', la durée par défaut est 24h)
une construction aléatoire (il ne contient plus le login et le mot de passe de l'utilisateur)
lors d'un accès Web :
Le jeton de sécurité possède les caractéristiques suivantes :
il est généré à partir du jeton de session
il a une durée de vie de 24h par défaut (configurable dans le fichier 'serverConf.xml')
il est stocké dans la console Adobe Campaign
lors d'un accès Web :
Lors d'un accès console, il est :
Lors d'un POST et GET HTTP :
Lors d'un appel SOAP :
var cnx = new HttpSoapConnection("https://serverURL/nl/jsp/soaprouter.jsp");
var session = new SoapService(cnx, 'urn:xtk:session');
session.addMethod("Logon", "xtk:session#Logon",
["sessiontoken", "string", "Login", "string", "Password", "string", "Parameters", "NLElement"],
["sessionToken", "string", "sessionInfo", "NLElement", "securityToken", "string"]);
var res = session.Logon("", "admin", "pwd", <param/>);
var sessionToken = res[0];
var securityToken = res[2];
cnx.addTokens(sessionToken, securityToken);
var query = new SoapService(cnx, 'urn:xtk:queryDef');
query.addMethod("ExecuteQuery", "xtk:queryDef#ExecuteQuery",
["sessiontoken", "string", "entity", "NLElement"],
["res", "NLElement"]);
var queryRes = query.ExecuteQuery("", <queryDef operation="select" schema="nms:recipient">
<select>
<node expr="@email"/>
<node expr="@lastName"/>
<node expr="@firstName"/>
</select>
<where>
<condition expr="@email = 'joe.doe@aol.com'"/>
</where>
</queryDef>);
logInfo(queryRes[0].toXMLString())
Les URL utilisées dans les appels HttpServletRequest suivants doivent être placées dans la liste autorisée dans la section des autorisations d'URL du fichier serverConf.xml. C'est également vrai pour l'URL du serveur lui-même.
Exécution du logon() :
var req = new HttpClientRequest("https://serverURL/nl/jsp/soaprouter.jsp");
req.header["Content-Type"] = "text/xml; charset=utf-8";
req.header["SOAPAction"] = "xtk:session#Logon";
req.method = "POST";
req.body = '<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:urn="urn:xtk:session">' +
'<soapenv:Header/>' +
'<soapenv:Body>' +
'<urn:Logon>' +
'<urn:sessiontoken></urn:sessiontoken>' +
'<urn:strLogin>LOGIN_HERE</urn:strLogin>' +
'<urn:strPassword>PASSWORD_HERE</urn:strPassword>' +
'<urn:elemParameters></urn:elemParameters>' +
'</urn:Logon>' +
'</soapenv:Body>' +
'</soapenv:Envelope>';
req.execute();
var resp = req.response;
var xmlRes = new XML(String(resp.body).replace("<?xml version='1.0'?>",""));
var sessionToken = String(xmlRes..*::pstrSessionToken);;
var securityToken = String(xmlRes..*::pstrSecurityToken);
Exécution de la requête :
var req2 = new HttpClientRequest("https://serverURL/nl/jsp/soaprouter.jsp");
req2.header["Content-Type"] = "text/xml; charset=utf-8";
req2.header["SOAPAction"] = "xtk:queryDef#ExecuteQuery";req2.header["X-Security-Token"] = securityToken;
req2.header["cookie"] = "__sessiontoken="+sessionToken;
req2.method = "POST";
req2.body = '<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:urn="urn:xtk:queryDef">' +
'<soapenv:Header/><soapenv:Body><urn:ExecuteQuery><urn:sessiontoken/><urn:entity>' +
'<queryDef operation="select" schema="nms:recipient">' +
'<select><node expr="@email"/><node expr="@lastName"/><node expr="@firstName"/></select>' +
'<where><condition expr="@email = \'john.doe@aol.com\'"/></where>' +
'</queryDef>' +
'</urn:entity></urn:ExecuteQuery></soapenv:Body></soapenv:Envelope>';
req2.execute();
var resp2 = req2.response;
logInfo(resp2.body)