v7

Appels Web Service

Informations générales

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 :

• Alertes synchrones, notifications et exécution de modèles de diffusion en temps-réel depuis un back-office ou un système transactionnel,
• Développement d'interfaces spécifiques avec des fonctionnalités simplifiées (interfaces Web, etc.),
• Alimentation et consultation des données de la base en respectant les règles métiers et en restant isolé du modèle physique sous-jacent.

Définition des services Web

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

Description des services Web : WSDL

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.

Génération du fichier WSDL

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)

Exemple sur la méthode 'ExecuteQuery' du schéma 'xtk:queryDef'

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.

Types

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>

Messages

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>

PortType

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>

Binding

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>

Service

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>

Connectivité

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 :

• via un appel à la méthode logon(). Ce mode génère un jeton de session et un jeton de sécurité. C'est le mode le plus sécurisé et donc celui qui est conseillé.

ou

• via login et mot de passe Adobe Campaign qui crée un jeton de session. Le jeton de session expire automatiquement après un délai. Ce mode est déconseillé et il demande de réduire les paramètres de sécurité de l'application dans la configuration des zones (allowUserPassword="true" et sessionTokenOnly="true").

Caractéristiques du jeton de session

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 session devient un jeton permanent, il n'est pas détruit lorsque le navigateur est fermé
  • il est placé dans un cookie HTTP-ONLY (activation des cookies obligatoire pour les opérateurs)

Caractéristiques du jeton de sécurité

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 :

  • il est stocké dans une propriété document.__securityToken
  • les URL de la page sont mises à jour pour actualiser le jeton de sécurité
  • les formulaires sont également mises à jour via un champ caché contenant le jeton

Circulation du jeton de sécurité

Lors d'un accès console, il est :

• transmis dans la réponse du logon (dans l'en-tête HTTP)
• utilisé à chaque requête (dans l'en-tête HTTP)

Lors d'un POST et GET HTTP :

• le serveur complète les liens avec le jeton
• le serveur ajoute un champ caché aux formulaires

Lors d'un appel SOAP :

• il est ajouté aux en-têtes de l'appel

Exemples d'appels

• En utilisant HttpSoapConnection/SoapService :

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

• En utilisant HttpServletRequest :

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)