@adobe/acc-js-sdk 1.1.1 → 1.1.4

package/.github/workflows/npm-publish.yml

@@ -16,7 +16,7 @@ jobs:
         node-version: 10.0.0
     - name: Publish if version has been updated
       #uses: pascalgn/npm-publish-action@06e0830ea83eea10ed4a62654eeaedafb8bf50fc
-      uses: mkiki/npm-publish-action@c4315ef5790b7bcec2cbb75b34e37681a409d78d
+      uses: mkiki/npm-publish-action@52879298d00c0a02781e1f02c9e917e01cff1bc7
       with: # All of theses inputs are optional
         tag_name: "v%s"
         tag_message: "v%s"

package/CHANGELOG.md

@@ -5,6 +5,35 @@ This is a node.js SDK for Campaign API. It exposes the Campaign API exactly like
 
 # Changelog 
 
+## Version 1.1.4
+_2022/06/xx_
+
+* Added `application.version` which returns the server version in the format major.minor.servicePack (ex: 8.2.10)
+* Added the ability to push down parameters to the SOAP and transport layers. See the pushDown section of the readme file.
+* The pushDown mechanism can be used to simply overwrite the request timeout, either globally or at the method level
+* Publicly export the HttpError class so that custom transports can be written more safely. A failure during transport should return an HttpError object
+* By default, the SOAP method name is now added in the URLs for better troubleshooting
+
+## Version 1.1.3
+_2022/05/30_
+
+* Fix a bug in client.hasPackage which was returning an incorrect result when passed a single parameter (it would always return false). Fixed the corresponding unit test too.
+* Fix a bug causing API calls having a input parameter of type "int" to fail. Usually the type is described as "long", but sometimes "int" is used instead, such as, for instance, in the nms:extAccount#UpdateMCSynchWkf method.
+* When using XML representations and DOMDocument method parameter type, the SDK expects to be passed an actual DOM document. Now it supports being passed a DOM element too. This is a common case when using the nms:delivery#createFromModel API followed by a xtk:session#Write API call.
+* Avoid the error 'Cannot transform entity to xml because no XML root name was given' by using SOAP method parameter name as the default for XML document root when no other root is available
+* Document how to set the password of an external account
+* By default, SDK will send additional HTTP headers to help troubleshooting and usage tracking
+* Add the ability to pass extra HTTP headers to API calls, either globally (to all HTTP headers), or locally, i.e. for a specific method
+* Remove .vscode folder from the sources
+* Example for xtkBuilder.installPackage API
+* For APIs which have parameters of type DOMElement and which are called using XML, support passing either a DOMElement or a DOMDocument
+
+
+## Version 1.1.2
+_2022/03/22_
+
+* Add support for choosing the representation (XML or JSON) at the method level using NLWS.xml or NLWS.json.
+
 ## Version 1.1.1
 _2022/03/10_
 

package/README.md

@@ -130,7 +130,11 @@ noStorage|false|De-activate using of local storage
 storage|localStorage|Overrides the local storage for caches
 refreshClient|undefined|Async callback to run when the session token is expired
 charset|UTF-8|The charset encoding used for http requests. In version 1.1.1 and above, the default will be UTF-8. It's possible to override (including setting an empty character set) with this option.
-
+extraHttpHeaders|[string]:string|An optional dictionary (key/value pairs) of extra HTTP headers to pass to all API calls.
+clientApp|string|An optional string describing the name and version of the SDK client application. It will be passed to the server in the ACC-SDK-Client-App HTTP header
+noSDKHeaders|boolean|Can be set to disable passing ACC-SDK-* HTTP headers to the server
+noMethodInURL|boolean|Can be set to true to remove the method name from the URL
+timeout|number|Can be used to set the APIs call timeout (in ms)
 ```js
 const connectionParameters = sdk.ConnectionParameters.ofUserAndPassword(
                                     "https://myInstance.campaign.adobe.com", 
@@ -187,8 +191,8 @@ If you want to use the SDK client-side in a web page returned by Campaign, you c
 For this scenario, the `ofSecurityToken` function can be used. Pass it a security token (usually available as document.__securitytoken), and the SDK will let the browser handle the session token (cookie) for you.
 
 ```html
-    <script src="acc-sdk.js"></script>
-    <script>
+<script src="acc-sdk.js"></script>
+<script>
         (async () => {
             try {
                 const sdk = document.accSDK;
@@ -202,8 +206,8 @@ For this scenario, the `ofSecurityToken` function can be used. Pass it a securit
                 console.error(ex);
             }
         })();
-    </script>
-    </body>
+</script>
+</body>
 </html>
 ```
 
@@ -304,12 +308,22 @@ const queryDef = {
 };
 ```
 
+## Method-level representation
+
+The client object is created with a default representation which is used for all API calls in the context of this client. Since version 1.1.2, it is also possible to set the representation at the method level, i.e. use a particular representation for a particular API call.
+
+* `client.NLWS`: use the default representation set at the client level
+* `client.NLWS.xml`: use the XML reresentation
+* `client.NLWS.json`: use the SimpleJson representation
+
+
 ## SimpleJson format
 The Simple JSON format works like this:
 
 The XML root element tag is determined by the SDK as it's generating the XML, usually from the current schema name.
 
-* XML: `<root/>`
+* XML: `<root/>
+`
 * JSON: `{}`
 
 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.
@@ -324,7 +338,7 @@ XML elements are mapped to JSON objects
 * XML: `<root><item id=1/></root>`
 * JSON: `{ item: { id:1 } }`
 
-If the parent element tag ends with `-collecion` 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. 
+If the parent element tag ends with `-collection` 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. 
 
 * XML: `<root-collection><item id=1/></root>`
 * JSON: `{ item: [ { id:1 } ] }`
@@ -346,7 +360,9 @@ Text of a child element
 * Alternative JSON: `{ item: { $: "Hello" } }`
 
 If an element contains both text, and children, you need to use the alternative `$` syntax
-* XML: `<root><item>Hello<child id="1"/></item></root>`
+* XML: `<root><item>Hello<child id="1"/>
+</item>
+</root>`
 * JSON: `{ item: { $: "Hello", child: { id:1 } }`
 
 
@@ -499,8 +515,8 @@ const DomUtil = client.DomUtil;
 Create DOM from XML string:
 ```js
 const doc = DomUtil.parse(`<root>
-      <one/>
-    </root>`);
+<one/>
+</root>`);
 ```
 
 Writes a DOM document or element as a string:
@@ -567,6 +583,49 @@ const document = DomUtil.fromJSON(json, "BadgerFish");
 const json = DomUtil.toJSON(documentOrElement, "BadgerFish");
 ```
 
+## Passing XML parameters
+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.
+
+```xml
+<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
+
+```js
+    await client.NLWS.nmsDelivery.DeployTriggerMessages({
+      condition: [ {
+        expr: "@internalName='DM23'"
+      }]
+    }, false);
+```
+
+The JSON object corresponds to the following XML
+```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:
+```js
+    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.
+
 ## Error Management
 
 If an API call fails (SOAP fault or HTTP error), a `CampaignException` object is thrown. This object contains the following attributes
@@ -645,6 +704,107 @@ const password = cipher.decryptPassword(encryptedPassword);
 
 > **warning** This function is deprecated in version 1.0.0 of the SDK because it may break as we deploy Vault.
 
+In order to set the password of an external account, you can use the `encryptPassword` API as follow
+
+```js
+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);
+```
+
+
+## HTTP Headers
+
+### Out-of-the-box headers
+In version 1.1.3 and above, the SDK will pass additional HTTP headers automatically
+
+Header | Description
+-------|------------
+SOAPAction| name of the schema and SOAP method (ex: xtk:query#ExecuteQuery)
+ACC-SDK-Version| Version of the SDK making the scores
+ACC-SDK-Auth| Authentification type and ACC user
+ACC-SDK-Client-App| Name of the application calling the client SDK
+ACC-SDK-Call-RetryCount| In case an API call is retried, indicates the number of retries
+ACC-SDK-Call-Internal| Indicates that an API call is performed byt the SDK for its own purpose
+
+The `ACC-SDK` headers can be removed using the connection parameter `noSDKHeaders`.
+
+### Custom HTTP headers
+In version 1.1.3 and above, it is possible to pass additional HTTP headers or override HTTP headers set by the SDK. This can be done globally (i.e. for all API calls), or locally, i.e. just for a particular call, or both.
+
+Http headers are passed through an object whose keys represent the header name and values the corresponding header value. Nothing particular is done in term of case sensitivity, headers will be passed as passed.
+
+To set global HTTP headers for all API calls of a client, pass an http headers array in the connection parameters
+```js
+const connectionParameters = sdk.ConnectionParameters.ofUserAndPassword(
+                                    "https://myInstance.campaign.adobe.com", 
+                                    "admin", "admin",
+                                    { extraHttpHeaders: {
+                                        "X-ACC-JS-SDK-LBSAFE": "1",
+                                        "X-ACC-WEBUI-VERSION: "1.2"
+                                    } });
+```
+
+Subsequent API calls will have the corresponding headers set.
+
+To set more HTTP headers for a particular API call, use the "headers" method of the NLWS object.
+
+```js
+const query = client.NLWS
+    .headers({'X-Test': 'hello'})
+    .xtkQueryDef.create(queryDef);
+await query.executeQuery();
+```
+
+## Timeouts
+
+By default, the SDK has a timeout of 5s when running in a node.js environment, and uses the browser defaults when run inside a browser (using the fetch API).
+
+It is possible to overwrite the transport layer (see `The Transport Protocol` and use your own code to make and configure HTTP requests) to tune the timeout value. It is a bit cumbersome though.
+
+Instead, you can use the `timeout` parameter, and set it either globally, as a connection parameter, or even at the API call level but using the `PushDown` mechanism described below.
+
+Sets a timeout of 10s gloally
+```js
+const connectionParameters = sdk.ConnectionParameters.ofUserAndPassword(
+                                    "https://myInstance.campaign.adobe.com", 
+                                    "admin", "admin",
+                                    { timeout: 10000 });
+```
+
+Override the timeout to 1 min for a particular API call
+```js
+NLWS.xml.pushDown({ timeout: 60000 }).xtkBuilder.installPackage(dom);
+```
+
+## Pushdown mechanism
+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.
+
+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.
+
+Any key/value pairs can be pushed down. This example pushes down the timeout and foo variables to the transport layer.
+```js
+NLWS.xml.pushDown({ timeout: 60000, foo: 'bar' }).xtkBuilder.installPackage(dom);
+```
+
+## Troubleshooting
+In the version 1.1.4 of the SDK, we are automatically adding the SOAP method name in the URL in order to simplify troubleshooting. Normally, all SOAP method calls are make to the soaprouter.jsp endpoint, which makes it difficult to understand which actual API call is being made.
+In fact the SOAP call name is available via the SOAPAction HTTP header, but it's usually not immediatelly visible.
+
+The SOAP calls URLs are now formed like this: `http://acc-sdk:8080/nl/jsp/soaprouter.jsp?xtk:queryDef#ExecuteQuery` where the SOAP method name is added as a query parameter. Campaign server ignores this parameter.
+
+This can be disabled using the `noMethodInURL` connection parameter
+
+const connectionParameters = sdk.ConnectionParameters.ofUserAndPassword(
+                                    "https://myInstance.campaign.adobe.com", 
+                                    "admin", "admin",
+                                    { noMethodInURL: true });
 
 
 # Samples
@@ -870,12 +1030,16 @@ The transport protocol defines
 - What is the corresponding response
 - How errors are handled
 
-The transport protocol exports a single asynchronous function `request` which takes a `Request` literal object with the following attributes. Note that it matches axios requests.
+The transport protocol exports a single asynchronous function `request` which takes two parameters.
+
+The first parameter is the request object with the following attributes. Note that it matches axios requests.
 * `method` is the HTTP verb
 * `url` is the URL to call
 * `headers` is an object containing key value pairs with http headers and their values
 * `data` is the request payload
 
+The second parameter is an set of additional parameters that have been pushed down to the transport layer (see the `Pushdown` paragraph for more details). In particular, the `timeout` parameter should be honored by the transport layer.
+
 If the request is successful, a promise is returned with the result payload, as a string.
 
 If the request fails, the promise is rejected with an error object with class `HttpError`, a litteral with the following attributes:
@@ -883,7 +1047,7 @@ If the request fails, the promise is rejected with an error object with class `H
 * `statusText` is the HTTP status text coming with the error
 * `data` is the response data, if any
 
-For proper error handling by the ACC SDK, it's important that the actual class of returned objects is names "HttpError"
+For proper error handling by the ACC SDK, it's important that the actual class of returned objects is named "HttpError"
 
 The transport can be overriden by using the `client.setTransport` call and passing it a transport function, i.e. an async function which
 * Takes a `Request` object litteral as a parameter
@@ -940,14 +1104,14 @@ 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">
 <SOAP-ENV:Header>
-    <Cookie>__sessiontoken=***</Cookie>
-    <X-Security-Token>***</X-Security-Token>
+<Cookie>__sessiontoken=***</Cookie>
+<X-Security-Token>***</X-Security-Token>
 </SOAP-ENV:Header>
 <SOAP-ENV:Body>
-    <m:GetOption xmlns:m="urn:xtk:session" SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
-        <sessiontoken xsi:type="xsd:string">***</sessiontoken>
-        <name xsi:type="xsd:string">XtkDatabaseId</name>
-    </m:GetOption>
+<m:GetOption xmlns:m="urn:xtk:session" SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
+<sessiontoken xsi:type="xsd:string">***</sessiontoken>
+<name xsi:type="xsd:string">XtkDatabaseId</name>
+</m:GetOption>
 </SOAP-ENV:Body>
 </SOAP-ENV:Envelope>
 
@@ -957,10 +1121,10 @@ xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance'
 xmlns:ns='urn:xtk:session'
 xmlns:SOAP-ENV='http://schemas.xmlsoap.org/soap/envelope/'>
 <SOAP-ENV:Body>
-    <GetOptionResponse xmlns='urn:xtk:session' SOAP-ENV:encodingStyle='http://schemas.xmlsoap.org/soap/encoding/'>
-        <pstrValue xsi:type='xsd:string'>uFE80000000000000F1FA913DD7CC7C4804BA419F</pstrValue>
-        <pbtType xsi:type='xsd:byte'>6</pbtType>
-    </GetOptionResponse>
+<GetOptionResponse xmlns='urn:xtk:session' SOAP-ENV:encodingStyle='http://schemas.xmlsoap.org/soap/encoding/'>
+<pstrValue xsi:type='xsd:string'>uFE80000000000000F1FA913DD7CC7C4804BA419F</pstrValue>
+<pbtType xsi:type='xsd:byte'>6</pbtType>
+</GetOptionResponse>
 </SOAP-ENV:Body>
 </SOAP-ENV:Envelope>
 `````
@@ -1135,6 +1299,17 @@ const folder = {
 await NLWS.xtkSession.write(folder);
 ````
 
+Some objects, such as deliveries are created from templates. The `createFromModel` API is preferred in this case. Given a template name, and a patch object, it will return an object created from the template and the patch, applying all sort of business rules and default values. This object can be inserted using a writer.
+
+In this example, an email delivery is created from the "mail" delivery template and it's label is set to "Hello".
+
+Note the xtkschema attribute in the second parameter of the `createFromModel` API call which is needed for the SDK to perform the proper JSON to XML transformation.
+
+```js
+const mail = await client.NLWS.nmsDelivery.createFromModel('mail', { xtkschema:'nms:delivery', label:'Hello'});
+await client.NLWS.xtkSession.write(mail);
+````
+
 # Workflow API
 
 Start and stop wotkflows, passing either an id or workflow internal name
@@ -1338,6 +1513,7 @@ The `application` object can be obtained from a client, and will mimmic the Camp
 | Attribute/Method | Description |
 |---|---|
 | **buildNumber** | The server build number
+| **version** | In SDK version 1.1.4 and above, returns the server version formatted as major.minor.servicePack (ex: 8.2.10)
 | **instanceName** | The name of the Campaign instance
 | **operator** | Information about the current operator (i.e. logged user), of class `CurrentLogin`
 | **packages** | List of installed packages, as an array of strings

package/compile.js

@@ -38,8 +38,8 @@ var resources = [
     { name: "./optionCache.js" },
     { name: "./soap.js" },
     { name: "./crypto.js" },
-    { name: "./testUtil.js" },
     { name: "./application.js" },
+    { name: "./testUtil.js" },
     { name: "./client.js" },
     { name: "./index.js" },
 ];

package/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "@adobe/acc-js-sdk",
-  "version": "1.1.0",
+  "version": "1.1.4",
   "lockfileVersion": 2,
   "requires": true,
   "packages": {
     "": {
       "name": "@adobe/acc-js-sdk",
-      "version": "1.1.0",
+      "version": "1.1.4",
       "license": "ISC",
       "dependencies": {
         "axios": "^0.25.0",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adobe/acc-js-sdk",
-  "version": "1.1.1",
+  "version": "1.1.4",
   "description": "ACC Javascript SDK",
   "main": "src/index.js",
   "homepage": "https://github.com/adobe/acc-js-sdk#readme",

package/samples/011 - basics - packages.js

@@ -0,0 +1,60 @@
+/*
+Copyright 2020 Adobe. All rights reserved.
+This file is licensed to you under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License. You may obtain a copy
+of the License at http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software distributed under
+the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+OF ANY KIND, either express or implied. See the License for the specific language
+governing permissions and limitations under the License.
+*/
+const { DomUtil } = require('../src/domUtil.js');
+const sdk = require('../src/index.js');
+const utils = require("./utils.js");
+
+
+/**
+ * This sample illustrates how to generate and import packages
+ */
+
+( async () => {
+
+  await utils.sample({
+    title: "Testing generating and importing packages",
+    labels: [ "Basics", "Packages", "xtk:builder", "InstallPackage" ],
+    description: `The xtkBuilder.installPackage() can be used to import packages`,
+    code: async() => {
+      return await utils.logon(async (client, NLWS) => {
+        console.log(`Generating package with an option named AccJsSdk`);
+        const doc =  sdk.DomUtil.newDocument('pkgDesc');
+        const package = doc.createElement('package');
+        doc.documentElement.appendChild(package);
+        package.setAttribute('namespace', 'cus');
+        package.setAttribute('name', 'sdk');
+        package.setAttribute('buildNumber', '*');
+        package.setAttribute('buildVersion', '*');
+        package.setAttribute('label', 'Test package for ACC JS SDK');
+        package.setAttribute('vendor', 'acc-js-sdk');
+        
+        const entities = doc.createElement('entities');
+        package.appendChild(entities);
+        entities.setAttribute('schema', 'xtk:option');
+      
+        const option = doc.createElement('option');
+        option.setAttribute('name', 'AccJsSdk');
+        option.setAttribute('dataType', '6');
+        const version = client.application.version;
+        option.setAttribute('stringValue', JSON.stringify(version));
+        entities.appendChild(option);
+      
+        // Install package. The package is in XML format and we set the timeout to 5 mins to prevent any issues
+        console.log(`Installing package`, DomUtil.toXMLString(doc));
+        await NLWS.xml.pushDown({ timeout: 5*60*1000 }).xtkBuilder.installPackage(doc);      
+        console.log(`Package installed`);
+      });
+    }
+  });
+
+})();
+

package/samples/utils.js

@@ -47,7 +47,9 @@ async function run(main) {
  */
 async function logon(callback) {
   var main = async () => {
-    const connectionParameters = sdk.ConnectionParameters.ofUserAndPassword(url, user, password);
+    const connectionParameters = sdk.ConnectionParameters.ofUserAndPassword(url, user, password, {
+      clientApp: 'acc-js-sdk sample'
+    });
     const client = await sdk.init(connectionParameters);
     const NLWS = client.NLWS;
   

package/src/application.js

@@ -1207,23 +1207,30 @@ class Application {
              * The server build number
              * @type {string}
              */
-        this.buildNumber = EntityAccessor.getAttributeAsString(serverInfo, "buildNumber");
+            this.buildNumber = EntityAccessor.getAttributeAsString(serverInfo, "buildNumber");
+            /**
+             * The server version, formatted as major.minor.servicePack (ex: 8.2.10)
+             * @type {string}
+             */
+            this.version = EntityAccessor.getAttributeAsString(serverInfo, "majNumber") + "." +
+                           EntityAccessor.getAttributeAsString(serverInfo, "minNumber") + "." +
+                           EntityAccessor.getAttributeAsString(serverInfo, "servicePack");
             /**
              * The Campaign instance name
              * @type {string}
              */
-        this.instanceName = EntityAccessor.getAttributeAsString(serverInfo, "instanceName");
+            this.instanceName = EntityAccessor.getAttributeAsString(serverInfo, "instanceName");
             const userInfo = EntityAccessor.getElement(info, "userInfo");
             /**
              * The logged operator
              * @type {Campaign.CurrentLogin}
              */
-        this.operator = new CurrentLogin(userInfo);
+            this.operator = new CurrentLogin(userInfo);
             /**
              * The list of installed packages
              * @type {string[]}
              */
-        this.packages = [];
+            this.packages = [];
             for (var p of EntityAccessor.getChildElements(userInfo, "installed-package")) {
             this.packages.push(`${EntityAccessor.getAttributeAsString(p, "namespace")}:${EntityAccessor.getAttributeAsString(p, "name")}`);
             }