@adobe/acc-js-sdk 1.1.10 → 1.1.12

package/docs/midSourcing.html

@@ -0,0 +1,19 @@
+---
+layout: page
+title: Connect to mid-sourcing
+---
+
+<p>From a marketing client connection, one can get a client to a mid server</p>
+
+<pre class="code">
+console.log("Connecting to mid server...");
+const credentials = await sdk.Credentials.ofExternalAccount(client, "defaultEmailMid");
+const midClient = await sdk.init(credentials);
+
+await midClient.client.logon();
+const datbaseId = await midClient.getOption("XtkDatabaseId");
+console.log("Mid datbaseId: " + datbaseId);
+await midClient.NLWS.xtkSession.testCnx();
+console.log("Disconnecting from mid");
+await midClient.client.logoff();
+</pre>

package/docs/observability.html

@@ -0,0 +1,169 @@
+---
+layout: page
+title: Observability
+---
+
+
+<p>The Campaign client implements an observer mechanism that you can use to hook into what's hapenning internally.</p>
+
+<p>An <b>Observer</b>is an object having any of the following methods:</p>
+
+<p>For SOAP calls</p>
+<ul>
+    <li>onSOAPCall(soapCall, safeCallData)</li>
+    <li>onSOAPCallSuccess(soapCall, safeCallResponse) {}</li>
+    <li>onSOAPCallFailure(soapCall, exception) {}</li>
+</ul>
+
+<p>For HTTP calls (such as JSP, JSSP...). Note that despite SOAP calls are also HTTP calls, the following callbacks will not be called for SOAP calls.</p>
+
+<ul>
+    <li>onHTTPCall(request, safeCallData)</li>
+    <li>onHTTPCallSuccess(request, safeCallResponse) {}</li>
+    <li>onHTTPCallFailure(request, exception) {}</li>
+</ul>
+
+<p>The <b>soapCall</b>parameter is the SOAP call which is being observed. In the <b>onSOAPCall</b>callback, the SOAP call has not been executed yet.</p>
+
+<p>The <b>request</b>parameter is the HTTP request (as defined in the transport protocol above)</p>
+
+<p>The <b>safeCallData</b>and <b>safeCallResponse</b>represent the text XML of the SOAP request and response, but in which all session and security tokens have been replaced with "***" string. Hence the name "safe". You should use those parameters for any logging purpose to avoid leaking credentials.</p>
+
+
+<p>The <b>soapCall</b>parameter is a <b>SoapMethodCall</b>object which describes the SOAP call. It has the following public attributes. </p>
+
+<ul>
+    <li><b>urn</b>is the SOAP URN which corresponds to the Campaign schema id. For instance "xtk:session"</li>
+    <li><b>methodName</b>is the name of the method to call. For instance "Logon"</li>
+    <li><b>internal</b>is true or false, depending if the SOAP call is an internal SOAP call performed by the framework itself, or if it's a SOAP call issued by a SDK user</li>
+    <li><b>request</b>is a literal corresponding to the HTTP request. It's compatible with the <b>transport</b>protocol. It may be undefined if the SOAP call has need been completely built</li>
+    <li><b>response</b>is a string containing the XML result of the SOAP call if the call was successful. It may be undefined if the call was not executed yet or if the call failed</li>
+</ul>
+
+<p>In version 1.1.7, the observer interface is extended to listen for internal events of the SDK. The <b>event</b>function of the observer, if it exist will be call for each SDK event with 2 parameters: the event itself, and for some events, a parent event. For instance a SOAP response event will have the SOAP request for a parent event.</p>
+
+<pre class="code">
+client.registerObserver({
+    event: (event, parentEvent) => { ... },
+});
+</pre>
+
+<p>The following events are available</p>
+
+<table>
+    <thead>
+        <tr>
+            <th>Event name</th>
+            <th>Comment / Description</th>
+        </tr>
+    </thead>
+    <tbody>
+        <tr>
+            <td>SDK//logon</td>
+            <td>A client logs on</td>
+        </tr>
+        <tr>
+            <td>SDK//logoff</td>
+            <td>A client logs off</td>
+        </tr>
+        <tr>
+            <td>CACHE//stats</td>
+            <td>Regularly sends stats about internal caches</td>
+        </tr>
+        <tr>
+            <td>SOAP//request</td>
+            <td>The SDK executes a SOAP request</td>
+        </tr>
+        <tr>
+            <td>SOAP//response</td>
+            <td>The SDK processes the successful response of a SOAP request</td>
+        </tr>
+        <tr>
+            <td>SOAP//failure</td>
+            <td>A SOAP request failed</td>
+        </tr>
+        <tr>
+            <td>HTTP//request</td>
+            <td>The SDK executes an HTTP request</td>
+        </tr>
+        <tr>
+            <td>HTTP//response</td>
+            <td>The SDK processes the successful response of an HTTP request</td>
+        </tr>
+        <tr>
+            <td>HTTP//failure</td>
+            <td>An HTTP request failed</td>
+        </tr>
+        <tr>
+            <td>CACHE_REFRESHER//start</td>
+            <td>A cache auto-refresher starts</td>
+        </tr>
+        <tr>
+            <td>CACHE_REFRESHER//stop</td>
+            <td>A cache auto-refresher stops</td>
+        </tr>
+        <tr>
+            <td>CACHE_REFRESHER//tick</td>
+            <td>A cache auto-refresh occurs</td>
+        </tr>
+        <tr>
+            <td>CACHE_REFRESHER//loggedOff</td>
+            <td>The cache auto-refresh was triggered whereas the client was logged of</td>
+        </tr>
+        <tr>
+            <td>CACHE_REFRESHER//error</td>
+            <td>The cache auto-refresh failed. Auto-refresh will continue.</td>
+        </tr>
+        <tr>
+            <td>CACHE_REFRESHER//abort</td>
+            <td>The cache auto-refresh failed because the server does not support it. Auto-refresh will stop.</td>
+        </tr>
+        <tr>
+            <td>CACHE_REFRESHER//response</td>
+            <td>The server responded to an auto-refresh request</td>
+        </tr>
+    </tbody>
+</table>
+
+
+
+<h1>Logging all SOAP calls</h1>
+
+<p>SOAP calls can be logged by setting the <b>traceAPICalls</b>attribute on the client at any time. For security reasons, the security and session tokens values will be replaced by "***" to avoid leaking them</p>
+
+
+<pre class="code">
+client.traceAPICalls(true);
+</pre>
+
+<p>This is an example of the logs</p>
+<pre class="code">
+SOAP//request xtk:session#GetOption &lt;SOAP-ENV:Envelope xmlns:xsd="http://www.w3.org/2001/XMLSchema"
+xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
+xmlns:ns="http://xml.apache.org/xml-soap">
+&lt;SOAP-ENV:Header>
+&lt;Cookie>__sessiontoken=***&lt;/Cookie>
+&lt;X-Security-Token>***&lt;/X-Security-Token>
+&lt;/SOAP-ENV:Header>
+&lt;SOAP-ENV:Body>
+&lt;m:GetOption xmlns:m="urn:xtk:session" SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
+&lt;sessiontoken xsi:type="xsd:string">***&lt;/sessiontoken>
+&lt;name xsi:type="xsd:string">XtkDatabaseId&lt;/name>
+&lt;/m:GetOption>
+&lt;/SOAP-ENV:Body>
+&lt;/SOAP-ENV:Envelope>
+
+SOAP//response xtk:session#GetOption &lt;?xml version='1.0'?>
+&lt;SOAP-ENV:Envelope xmlns:xsd='http://www.w3.org/2001/XMLSchema'
+xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance'
+xmlns:ns='urn:xtk:session'
+xmlns:SOAP-ENV='http://schemas.xmlsoap.org/soap/envelope/'>
+&lt;SOAP-ENV:Body>
+&lt;GetOptionResponse xmlns='urn:xtk:session' SOAP-ENV:encodingStyle='http://schemas.xmlsoap.org/soap/encoding/'>
+&lt;pstrValue xsi:type='xsd:string'>uFE80000000000000F1FA913DD7CC7C4804BA419F&lt;/pstrValue>
+&lt;pbtType xsi:type='xsd:byte'>6&lt;/pbtType>
+&lt;/GetOptionResponse>
+&lt;/SOAP-ENV:Body>
+&lt;/SOAP-ENV:Envelope>
+</pre>

package/docs/passwords.html

@@ -0,0 +1,27 @@
+---
+layout: page
+title: Passwords
+---
+
+<p>External account passwords can be decrypted using a Cipher. This function is deprecated since version 1.0.0 since it's not guaranteed to work in future versions of Campaign (V8 and above)</p>
+
+<pre class="code">
+const cipher = await client.getSecretKeyCipher();
+const password = cipher.decryptPassword(encryptedPassword);
+</pre>
+
+<p class="warning">This function is deprecated in version 1.0.0 of the SDK because it may break as we deploy Vault.</p>
+
+<p>In order to set the password of an external account, you can use the <b>encryptPassword</b> API as follow</p>
+
+<pre class="code">
+const password = await this._client.NLWS.xtkSession.encryptPassword('password');
+const account = {
+    xtkschema: "nms:extAccount",
+    name: name,
+    account: 'admin',
+    server: server,
+    password: password,
+};
+await this._client.NLWS.xtkSession.Write(account);
+</pre>

package/docs/profiles.html

@@ -0,0 +1,103 @@
+---
+layout: page
+title: Profiles & Subscriptions
+---
+
+
+<p>Create a recipient</p>
+<pre class="code">
+var recipient = {
+    xtkschema: "nms:recipient",
+    _operation: "insert",
+    firstName: "Thomas",
+    lastName: "Jordy",
+    email: "jordy@adobe.com"
+};
+await NLWS.xtkSession.write(recipient);
+</pre>
+
+<p>Create multiple recipients</p>
+<pre class="code">
+var recipients = {
+    xtkschema: "nms:recipient",
+    recipient: [
+        {
+            _operation: "insert",
+            firstName: "Christophe",
+            lastName: "Protat",
+            email: "protat@adobe.com"
+        },
+        {
+            _operation: "insert",
+            firstName: "Eric",
+            lastName: "Perrin",
+            email: "perrin@adobe.com"
+        }
+    ]
+};
+await NLWS.xtkSession.writeCollection(recipients);
+</pre>
+
+<p>List all recipients in Adobe</p>
+<pre class="code">
+var queryDef = {
+    schema: "nms:recipient",
+    operation: "select",
+    select: {
+        node: [
+            { expr: "@id" },
+            { expr: "@firstName" },
+            { expr: "@lastName" },
+            { expr: "@email" }
+        ]
+    },
+    where: {
+        condition: [
+            { expr: "GetEmailDomain(@email)='adobe.com'" }
+        ]
+    }
+}
+const query = NLWS.xtkQueryDef.create(queryDef);
+var recipients = await query.executeQuery();
+console.log(JSON.stringify(recipients));
+</pre>
+
+<p>Count total number of profiles</p>
+<pre class="code">
+var queryDef = {
+    schema: "nms:recipient",
+    operation: "count"
+}
+var query = NLWS.xtkQueryDef.create(queryDef);
+var count = await query.executeQuery();
+count = XtkCaster.asLong(count.count);
+console.log(count);
+</pre>
+
+<p>Update a profile. In this case, use the "@email" attribute as a key. If the `@_key` attribute is not specified, the primary key will be used.</p>
+<pre class="code">
+var recipient = {
+    xtkschema: "nms:recipient",
+    _key: "@email",
+    _operation: "update",
+    firstName: "Alexandre",
+    email: "amorin@adobe.com"
+};
+await NLWS.xtkSession.write(recipient);
+</pre>
+
+<p>Delete a profile</p>
+<pre class="code">
+var recipient = {
+    xtkschema: "nms:recipient",
+    _key: "@email",
+    _operation: "delete",
+    email: "amorin@adobe.com"
+};
+await NLWS.xtkSession.write(recipient);
+</pre>
+
+<p>Delete a set of profiles, based on condition. For instance delete everyone having an email address in adobe.com domain</p>
+<pre class="code">
+await NLWS.xtkSession.deleteCollection("nms:recipient", { condition: { expr: "GetEmailDomain(@email)='adobe.com'"} });
+</pre>

package/docs/pushDown.html

@@ -0,0 +1,13 @@
+---
+layout: page
+title: Push down mechanism
+---
+
+<p>The Pushdown mechanism can be used to push down variables to the transport layer. A common use case it to pass a custom timeout value down to the transport layer.</p>
+
+<p>The pushed down parameters are passed as a second parameter to the transport function. This parameter will contain all the connection parameters as well as any parameter that you can push down at the API call level. API call pushdowns can override default pushdowns.</p>
+
+<p>Any key/value pairs can be pushed down. This example pushes down the timeout and foo variables to the transport layer.</p>
+<pre class="code">
+NLWS.xml.pushDown({ timeout: 60000, foo: 'bar' }).xtkBuilder.installPackage(dom);
+</pre>

package/docs/quickstart.html

@@ -0,0 +1,69 @@
+---
+layout: page
+title: Quick Start
+---
+
+Here's a small node.js application which displays all the target mappings in Campaign.
+
+
+<p>Create a new node.js application</p>
+<pre class="code">
+mkdir acc-js-sdk-qstart
+cd acc-js-sdk-qstart
+</pre>
+
+<p>Install the SDK</p>
+<pre class="code">
+npm i --save @adobe/acc-js-sdk
+</pre>
+
+<p>Now create a simple <b>index.js</b> flle. Replace the endppoint and credentials with your own</p>
+
+<pre class="code">
+const sdk = require('@adobe/acc-js-sdk');
+
+(async () => {
+    // Display the SDK version
+    const version = sdk.getSDKVersion();
+    console.log(`${version.description} version ${version.version}`);
+
+    // Logon to a Campaign instance with user and password
+    const connectionParameters = sdk.ConnectionParameters.ofUserAndPassword(
+                                        "https://myInstance.campaign.adobe.com", 
+                                        "admin", "admin");
+    const client = await sdk.init(connectionParameters);
+    await client.logon();
+    const NLWS = client.NLWS;
+
+    // Get and display the list of target mappings
+    const queryDef = {
+        schema: "nms:deliveryMapping",
+        operation: "select",
+        select: {
+            node: [
+                { expr: "@id" },
+                { expr: "@name" },
+                { expr: "@label" },
+                { expr: "@schema" }
+            ]
+        }
+    };
+    const query = NLWS.xtkQueryDef.create(queryDef);
+    const mappings = await query.executeQuery();
+    console.log(`Target mappings: ${JSON.stringify(mappings)}`);
+})().catch((error) => {
+    console.log(error);
+});
+</pre>
+    
+<p>Run it</p>
+<pre class="code">
+node index.js
+</pre>
+
+<p>It will display something like this</p>
+<pre class="code">
+ACC Javascript SDK version 1.1.9
+Target mappings: {"deliveryMapping":[{"id":"1747","label":"Recipients","name":"mapRecipient","schema":"nms:recipient"},{"id":"1826","label":"Subscriptions","name":"mapSubscribe","schema":"nms:subscription"},{"id":"1827","label":"Operators","name":"mapOperator","schema":"xtk:operator"},{"id":"1828","label":"External file","name":"mapAny","schema":""},{"id":"1830","label":"Visitors","name":"mapVisitor","schema":"nms:visitor"},{"id":"2035","label":"Real time event","name":"mapRtEvent","schema":"nms:rtEvent"},{"id":"2036","label":"Batch event","name":"mapBatchEvent","schema":"nms:batchEvent"},{"id":"2070","label":"Subscriber applications","name":"mapAppSubscriptionRcp","schema":"nms:appSubscriptionRcp"}]}
+</pre>
+

package/docs/release.html

@@ -0,0 +1,52 @@
+---
+layout: page
+title: Releasing a new version
+---
+<p></p>
+
+<ul>
+  <li>First, increase the version in <b>package.json</b></li>
+  <li>Run <b>npm install</b> to update dependencies</li>
+</ul>
+
+
+<p>Then, make sure that the <a href="{{ site.baseurl }}/checkList.html">Commit Checklist</a> is fullfiled.</p>
+
+<ul>
+  <li>Check that tests run with 100% coverage</li>
+  <li>Check and resolve any security issues</li>
+  <li>Check if there are any code warnings</li>
+  <li>Check that JavaScript documentation builds and is complete</li>
+  <li>Check that your new features or fixed are documented and appear in the changelog</li>
+  <li>Check that the client-side library builds and work</li>
+</ul>
+
+<p>In a nutshell</p>
+
+<pre class="code">
+npm i
+npm run unit-tests
+npm audit
+node_modules/jshint/bin/jshint src/
+npm run jsdoc
+open ./docs/jsdoc/index.html
+node ./compile.js
+</pre>
+
+
+<p>To release and deploy to npm</p>
+
+<p>Push a commit with message <b>Release 1.2.3</b> in master<p>
+  
+<pre class="code">
+git commit -m "Release 1.2.3"
+git push origin
+</pre>
+
+<p class="info">There's a publication action that will publish released automatically when there's a commit named "Release ..." in master AND the version matches the one in package.json
+Do not create a git tag for this version, the publication hook will take care of it. If you have created a tag with the release name, the publication will fail
+</p> 
+
+<p>You can follow the results of the actions <a href="https://github.com/adobe/acc-js-sdk/actions">here</a></p>
+
+<p class="info">It usually takes a few hours for the package to show up in the <a href="https://www.npmjs.com/package/@adobe/acc-js-sdk">NPM UI</a> but you can still use the package by using npm</p>

package/docs/samples.html

@@ -0,0 +1,82 @@
+---
+layout: page
+title: Sample Code
+---
+
+<p>The <b>samples</b> folder contains several samples illustrating how to use the various Campaing APIs.</p>
+
+<p>A sample file looks like this</p>
+
+<ul>
+<li>It includes the <b>utils</b> library which contains a few helper functions.s</li>
+<li>It starts with an asynchronous auto-execute function that is used to run the sample from the command line</li>
+<li>This function contains one or more calls to the <b>utils.sample</b> function. Each such call describes and execute a sample.</li>
+<li>A sample file should not do anything else or have any side effect: all the actual sample code should be inside calls to <b>utils.sample</b></li>
+</ul>
+
+<p class="info"> Note the use of <b>await</b> when calling <b>utils.sample</b></p>
+
+<pre class="code">
+const utils = require("./utils.js");
+( async () => {
+  await utils.sample({
+    title: "The Sample title",
+    labels: [ "xtk:queryDef", "Basics", "Query", "QueryDef", "Get" ],
+    description: `A description of the sample`,
+    code: async() => {
+      //... Sample code goes there
+    }
+  });
+
+  await utils.sample({
+    title: "A Second sample",
+    labels: [ "xtk:queryDef", "Basics", "Query", "QueryDef", "Get" ],
+    description: `A description of the sample`,
+    code: async() => {
+      //... Sample code goes there
+    }
+  });
+})();
+</pre>
+
+<p>The <b>utils.sample</b> function takes 1 parameters describing the sample:</p>
+<ul>
+<li><b>title</b> is the sample title, a short, human friendly name for the sample</li>
+<li><b>labels</b> is a list of keywords that can be used to retreive the samples in a large list</li>
+<li><b>description</b> is a longer, multi-line description of the sample</li>
+<li><b>code</b> is an async function, the code of the sample</li>
+</ul>
+
+<p>Most of the samples - actually all of them except some specific samples needing specific logon - will also use the `utils.logon` function. This is a helper function which will perform the Campaign Logon and Logoff for you, and call your callback function with pre-initialized `client` and `NLWS` objects</p>
+
+<p class="info"> Note the use of <b>await</b> when calling <b>utils.logon</b></p>
+
+<pre class="code">
+  await utils.sample({
+    title: "The Sample title",
+    labels: [ "xtk:queryDef", "Basics", "Query", "QueryDef", "Get" ],
+    description: `A description of the sample`,
+    code: async() => {
+      return await utils.logon(async (client, NLWS) => {
+          //... Sample code goes there
+      });
+    }
+  });
+</pre>
+
+
+<h1>Running samples</h1>
+<p>Samples can be run from the command line. First, set 3 environment variables with your instance credentials:</p>
+
+<pre class="code">
+export ACC_URL=https://myInstance.campaign.adobe.com
+export ACC_USERadmin
+export ACC_PASSWORD=...
+</pre>
+
+<p>and then run the samples</p>
+<pre class="code">
+node samples/000\ -\ basics\ -\ logon.js
+</pre>`
+
+

package/docs/simpleJson.html

@@ -0,0 +1,88 @@
+---
+layout: page
+title: SimpleJson format
+---
+
+<p>The <b>SimpleJson</b> format is the format used by default by the SDK to conver between Campaign XML and JSON</p>
+
+
+<ul>
+  <li>XML attributes are JSON properties (without the “@” sign)</li>
+  <li>XML elements are JSON objects</li>
+  <li>XML collections are JSON arrays</li>
+  <li>XML text use “$” sign</li>
+</ul>
+
+<p></p>
+<pre class="code">
+&lt;book title="A confederacy of dunces">          {
+  &lt;author>John Kennedy Toole&lt;/author>             "$author": "John Kennedy Toole",
+                                                  "chapter": [
+  &lt;chapter name="Chapter I" pages="20">             { "name": "Chapter I", 
+  &lt;/chapter>                                          "pages": 20 },
+  &lt;chapter name="Chapter II" pages="34">            { "name": "Chapter II", 
+  &lt;/chapter>                                          "pages": 3 },
+                                                  ]
+&lt;/book>                                         }
+</pre>
+
+
+<p>The XML root element tag is automatically determined by the SDK as it's generating the XML, usually from the current schema name.</p>
+
+<pre class="code">
+XML:     &lt;root/>
+JSON:    {}
+</pre>
+
+<p>XML attributes are mapped to JSON attributes with the same name, whose litteral value can be a string, number, or boolean. There's no "@" sign in the JSON attribute name.
+Values in JSON attributes can be indifferently typed (ex: number, boolean), or strings (ex: "3" instead of just 3) depending if the conversion could determine the attribute type or not. 
+API users should expect and handle both value and use the `XtkCaster` object to ensure proper conversion when using.</p>
+
+<pre class="code">
+XML     &lt;root hello="world" count="3" ok="true"/>
+JSON:   { hello:"world", count:"3", ok:"true" }
+</pre>
+
+<p>XML elements are mapped to JSON objects</p>
+
+<pre class="code">
+XML:    &lt;root>&lt;item id="1"/>&lt;/root>
+JSON:   { item: { id:"1" } }
+</pre>
+
+<p>If the parent element tag ends with <b>-collection</b> children are always an array, even if there are no children, or if there is just one child. The rationale is that XML/JSON conversion is ambigous : XML can have multiple elements with the same tag and when there's only one such element, it's not possible to determine if it should be represented as a JSON object or JSON array unless we have additional metadata. </p>
+
+<pre class="code">
+XML:    &lt;root-collection>&lt;item id=1/>&lt;/root>
+JSON:   { item: [ { id:"1" } ] }
+</pre>
+
+<p>When an XML element is repeated, an JSON array is used</p>
+
+<pre class="code">
+XML:    &lt;root>&lt;item id=1/>&lt;item id=2/>&lt;/root>
+JSON:   { item: [ { id:"1" }, { id:"2" } ] }
+</pre>
+
+<p>Text of XML element is handle with the <b>$</b> sign in the JSON attribute name, or with a child JSON object name <b>$</b></p>
+
+<p>Text of the root element</p>
+<pre class="code">
+XML:    &lt;root>Hello&lt;/root>
+JSON:   { $: "Hello" }
+</pre>
+
+<p>Text of a child element</p>
+<pre class="code">
+XML:    &lt;root>&lt;item>Hello&lt;/item>&lt;/root>`
+JSON:   { $item: "Hello" }
+Alternative JSON: { item: { $: "Hello" } }
+</pre>
+
+<p>If an element contains both text, and children, you need to use the alternative <b>$</b> syntax</p>
+<pre class="code">
+XML:    &lt;root>&lt;item>Hello&lt;child id="1"/>
+          &lt;/item>
+        &lt;/root>
+JSON:   { item: { $: "Hello", child: { id:"1" } }
+</pre>