The NLWS object allows to dynamically perform SOAP calls on the targetted Campaign instance.
const NLWS = client.NLWS;
Technically, NLWS is a JavaScript proxy whose properties are dynamically constructed. It has properties for each schema, for instance NLWS.xtkSession corresponds to the APIs of the xtk:session schema.
Methods can then be called as asynchronous JavaScript functions. Note that in Campaign, method names usually start with a capital letter (ex: xtk:session#GetServerTime where "G" is a capital letter). JavaScript convention is to use a lower case first character for function names, and the SDK will follow JS conventions.
const result = await NLWS.xtkSession.getServerTime();
In order to know which parameters to pass to a method and which parameters are returned, look at the method definition in the schema. You can also capture SOAP requests and responses from a real session. The method definition in the schema will have a list of parameters. Parameters can be qualified as in, out, or inout. Unqualified parameters are considered to be in (input) parameters.
The parameters marked as in, inout or without an inout attribubte are input parameters of the API and must be passed in JavaScript to the method call. Refer to the Data Types page for a comprehensive view of all the data types supported by the SDK. Parameters are passed positionally and not by name, i.e. you must pass each input parameter in the right order, skipping output parameters.
<method name="GetFilesToDownload" static="true">
<parameters>
<param name="deliveryId" type="long" inout="in"/>
<param name="filesToDownload" type="DOMDocument" inout="out"/>
<param name="filesNotToDownload" type="DOMDocument" inout="out"/>
</parameters>
</method>
An example of a method definition with in and out parameters
Another important attribute is the static attribute of each method. Static methods can be called directly. Non-static methods need an object instance. In the example above, the method takes one input parameter, a numeric delivery id, and returns 2 DOM documents containing a list of files to downoad and a list of files not to download.
const deliveryId = 1234; const [filesToDownload, filesNotToDownload] = client.NLWS.nmsDelivery.getFilesToDownload(deliveryId);
In Campaign, many method attributes are XML elements or documents, as well as many return types. It's not very easy to use in JavaScript, so the SDK supports automatic XML<=> JSON conversion. Of yourse, you can still use XML if you want.
We're supporting several flavors of JSON in addition to XML.
The representation can set when creating a client. It's recommended to keep it to SimpleJson.
const client = await sdk.init("https://myInstance.campaign.adobe.com", "admin", "admin", { representation: "SimpleJson" });
Here's an example of a queryDef in SimpleJson. This query will return an array containing one item for each external account in the Campaign database. Each item will contain the account id and name.
const queryDef = {
schema: "nms:extAccount",
operation: "select",
select: {
node: [
{ expr: "@id" },
{ expr: "@name" }
]
}
};
Static SOAP methods are the easiest to call. Once you have a NLWS object and have logged on to the server, call a static mathod as followed. This example will use the xtk:session#GetServerTime method to displayt the current timestamp on the server.
const NLWS = client.NLWS; result = await NLWS.xtkSession.getServerTime(); console.log(result);
Campaign APIs can return one or multiple values. The SDK uses the following convention:
To call a non-static API, you need an object to call the API on. You create an object with the create method. For instance, here's how one creates a QueryDef object.
const queryDef = {
schema: "nms:extAccount",
operation: "select",
select: {
node: [
{ expr: "@id" },
{ expr: "@name" }
]
}
};
const query = NLWS.xtkQueryDef.create(queryDef);
Note: the returned object is opaque and private, it should not be directly manipulated.
The method can then be called directly on the object
const extAccounts = await query.executeQuery();
In this example, the result is as follows
{ extAccount:[
{ id: "2523379", name: "cda_snowflake_extaccount" },
{ id: "1782", name: "defaultPopAccount" },
{ id: "3643548", name: "v8" }
]}
Some methods can mutate the object on which they apply. This is for instance the case of the xtk:queryDef#SelectAll method. You call it on a queryDef, and it internally returns a new query definition which contain select nodes for all the nodes of the schema. When such a method is called, the SDK will know how to "mutate" the corresponding object.
const queryDef = {
schema: "xtk:option",
operation: "get",
where: { condition: [ { expr:`@name='XtkDatabaseId'` } ] }
};
const query = client.NLWS.xtkQueryDef.create(queryDef);
await query.selectAll(false);
var result = await query.executeQuery();
In the previous example, a queryDef is created without any select nodes. Then the selectAll method is called. After the call, the JavaScript queryDef object will contain a select elements with all the nodes corresponding to attributes of the xtk:option schema.
Many Campaign APIs take arguments which are DOM documents or DOM elements. For example, the nms:delivery#DeployTriggerMessages first argument is a DOMElement which is supposed to be a <where> clause used as a condition to select Message Center deliveries to publish.
<method name="DeployTriggerMessages" static="true">
<parameters>
<param inout="in" name="deliveries" type="DOMElement"/>
<param inout="in" name="localPublish" type="boolean"/>
</parameters>
</method>
For example, one would want to use the following condition to republish a particular delivery
await client.NLWS.nmsDelivery.DeployTriggerMessages({
condition: [ {
expr: "@internalName='DM23'"
}]
}, false);
The JSON object corresponds to the following XML
<where>
<condition expr="@internalName='DM23'"/>
</where>
Note that in XML, unlike JSON, the root element <where> is explicitely named "where". When converting JSON to XML, there is no way for the SDK to know which tag name to used for the root XML element. The SDK contains some code to set it for the most common situation, but will rely on the user to specify, when necessary, the name of the root elment. This can be done using the xtkschema (all case insensitive) attribute as follows:
await client.NLWS.nmsDelivery.DeployTriggerMessages({
xtkschema: 'xtk:where',
condition: [ {
expr: "@internalName='DM23'"
}]
}, false);
When the xtkschema attribute is set, the part after the colon (i.e. "where" in this example) will be used as the root element, effectively generating the right XML.
In our example, the `DeployTriggerMessages` will work properly regardless of the XML root of its `deliveries` parameter, so it's not needed to actually set the `xtkschema` attribute, but it's a best practice to do so, because some APIs will actually depend on receiving the right tag name.