@adobe/acc-js-sdk 1.1.15 → 1.1.17

package/compile.js

@@ -31,6 +31,7 @@ var resources = [
     { name: "./transport.js" },
     { name: "./xtkCaster.js" },
     { name: "./domUtil.js" },
+    { name: "./xtkJob.js" },
     { name: "./cache.js" },
     { name: "./entityAccessor.js" },
     { name: "./xtkEntityCache.js" },

package/docs/_data/navigation.yml

@@ -83,6 +83,8 @@
       link: methodLevelRepresentation.html
     - name: XTK Interfaces
       link: xtkInterface.html
+    - name: XTK Jobs
+      link: xtkJob.html
     - name: Handling timeouts
       link: timeouts.html
     - name: HTTP Headers

package/docs/changeLog.html

@@ -2,6 +2,13 @@
 layout: page
 title: Change Log
 ---
+<section class="changelog"><h1>Version 1.1.16</h1>
+  <h2>2022/11/29</h2>
+  
+  <li>Added support for xtk:job interface and job-related methods. See <a href="https://opensource.adobe.com/acc-js-sdk/xtkJob.html">Jobs documentation</a> for more details</li>
+</section>
+
+
 <section class="changelog"><h1>Version 1.1.15</h1>
   <h2>2022/11/28</h2>
   

package/docs/observability.html

@@ -6,41 +6,95 @@ 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>An <b>Observer</b> is an object which has one or several callback methods which will be called at certain particular points in the SDK</p>
 
-<p>For SOAP calls</p>
+
+<h1>SOAP calls</h1>
+<p>It is possible to observe the SOAP calls that are performed by the SDK. The following callbacks are called whenever a SOAP call is made. They can observe the SOAP calls but are not supposed to modify any of the parameters</p>
+<p></p>
 <ul>
-    <li>onSOAPCall(soapCall, safeCallData)</li>
-    <li>onSOAPCallSuccess(soapCall, safeCallResponse) {}</li>
-    <li>onSOAPCallFailure(soapCall, exception) {}</li>
+    <li><b>onSOAPCall</b> (soapCall, safeCallData)</li>
+    <li><b>onSOAPCallSuccess</b> (soapCall, safeCallResponse) {}</li>
+    <li><b>onSOAPCallFailure</b> (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>
+<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>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>
+<p></p>
 <ul>
-    <li>onHTTPCall(request, safeCallData)</li>
-    <li>onHTTPCallSuccess(request, safeCallResponse) {}</li>
-    <li>onHTTPCallFailure(request, exception) {}</li>
+    <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>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>
+<h1>HTTP calls</h1>
+<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. These callbacks are not supposed to modify any of the parameters</p>
+<p></p>
+<ul>
+    <li><b>onHTTPCall</b> (request, safeCallData)</li>
+    <li><b>onHTTPCallSuccess</b> (request, safeCallResponse) {}</li>
+    <li><b>onHTTPCallFailure</b> (request, exception) {}</li>
+</ul>
 
 
-<p>The <b>soapCall</b>parameter is a <b>SoapMethodCall</b>object which describes the SOAP call. It has the following public attributes. </p>
+<p>The <b>request</b> parameter is the HTTP request (as defined in the transport protocol above)</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>
+<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>
+
+
+
+
+
+<h1>Observability events</h1>
+<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({
@@ -127,43 +181,46 @@ client.registerObserver({
 
 
 
-<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>
-
+<h1>Method interception</h1>
 
-<pre class="code">
-client.traceAPICalls(true);
-</pre>
+<p>
+    In version 1.1.17 of the SDK, it's possible to use the observer mechanism to intercept SOAP calls, modify parameters before the call is made, or modify the response before it's returned to the caller.
+</p>
+<p>
+    Some SOAP calls are not intercepted: internal SOAP calls performed by the SDK itself (for instance to get schemas) are not intercepted. Logon and Logoff methods are not intercepted either.
+</p>
+<p>
+    The <b>beforeSoapCall</b> and <b>afterSoapCall</b> methods can be used. They will be passed the following parameters
+</p>
 
-<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>
+<table>
+    <thead>
+        <tr>
+            <th>Parameter</th>
+            <th>Comment / Description</th>
+        </tr>
+    </thead>
+    <tbody>
+        <tr>
+            <td><b>method</b></td>
+            <td>An object describing the SOAP method. It contains the <b>urn</b>, <b>name</b> and <b>isStatic</b> attributes</td>
+        </tr>
+        <tr>
+            <td><b>object</b></td>
+            <td>The object ("this") on which the method applies (it will be undefined for static methods). The <b>beforeSoapCall</b> callback is free to modify the object as needed.</td>
+        </tr>
+        <tr>
+            <td><b>inputParameters</b></td>
+            <td>Is an array containing the method parameters. The <b>beforeSoapCall</b> callback is free to modify the object as needed. </td>
+        </tr>
+        <tr>
+            <td><b>representation</b></td>
+            <td>The representation (SimpleJson, xml, etc.) used for this method and in which the object and parameters are set</td>
+        </tr>
+        <tr>
+            <td><b>outputParameters</b></td>
+            <td>For the <b>afterSoapCall</b> method, an array containing the return value of the SOAP calls. The <b>afterSoapCall</b> callback is free to modify the object as needed. </td>
+        </tr>
+    </tbody>
+</table>
 
-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/xtkInterface.html

@@ -17,4 +17,4 @@ const delivery = client.NLWS.nmsDelivery.create({ label: "Hello" });
 await delivery.newInstance();
 </pre>
 
-<p>There are 2 common interfaces: <a href="{{ site.baseurl }}/xtkPersist.html">xtk:persist</a> and <a href="">xtk:jobInterface</a> which are documented below.</p>
+<p>There are 2 common interfaces: <a href="{{ site.baseurl }}/xtkPersist.html">xtk:persist</a> and <a href="{{ site.baseurl }}/xtkJob.html">xtk:jobInterface</a> which are documented below.</p>

package/docs/xtkJob.html

@@ -0,0 +1,131 @@
+---
+layout: page
+title: XTK Jobs (xkt:job, xkt:jobInterface)
+---
+<p>This section describes how long running jobs are handled in ACC and ACC api. There are 2 schemas for jobs</p>
+<ul>
+  <li>xtk:job which represents an acutal job, and which is implemented by several objects such as nms:delivery</li>
+  <li>xtk:jobInterface which contains methods to submit jobs and get their statuses. Other schemas do not actually implement the xtk:jobInterface interface</li>
+</ul>
+
+<p>In term of SOAP calls, running a job is simply executing a SOAP call synchronously or asynchronously in a separate thread or process. However, calls must be made on both the xtk:jobInterface and job entity schema. The SDK provides a helper interface to submit and handle jobs</p>
+
+<h1>Simple Jobs</h1>
+  
+<p>
+  Simple jobs are non-static methods with no parameters, such as the nms:delivery#Prepare method which is used to prepare a delivery. 
+  Such jobs can be executed synchronously (xtk:jobInterface#Execute) or asynchronously (xtk:jobInterface#Submit). Both methods return
+  a job id which can be used to retreive (poll) more about the job.
+<p>
+    
+<p>
+  First, we need to retreive a delivery, which is the object upon which to run the Prepare method, but also implements xtk:job interface. 
+  The Prepare method requires a complete delivery object, so we use SelectAll
+</p>
+
+<pre class="code">
+  const  queryDef = {
+    schema: "nms:delivery",
+    operation: "get",
+    select: { node: [ { expr: "@id" } ] },
+    where: { condition: [ { expr:`@internalName='DM19'` } ] }
+  }
+  const  query = NLWS.xtkQueryDef.create(queryDef);
+  await query.selectAll();
+  const delivery = await query.executeQuery();
+</pre>
+
+<p>
+  Now we can create a job for the Prepare method using the <b>client.jobInterface</b> function which returns a XtkJobInterface object. 
+  We pass it a job specification containing the schema, method, and object
+</p>
+
+<pre class="code">
+  const job = await client.jobInterface({
+    xtkschema: 'nms:delivery',
+    method: 'Prepare',
+    object: delivery
+  });
+</pre>
+
+<p>
+  Finally we can submit the job and get it's status, progress, result, etc.
+</p>
+
+<pre class="code">
+  await job.submit();
+  var status = await job.getStatus();
+</pre>
+
+
+<h1>Soap calls</h1>
+<p>
+  The <b>SubmitSoapCall</b> method allows to run more complex jobs with parameters. The principle is the same, for instance calling the <b>PrepareProof</b> method
+  which takes a boolean parameter
+</p>
+
+<pre class="code">
+  const job = await client.jobInterface({
+    xtkschema: 'nms:delivery',
+    method: 'PrepareProof',
+    object: delivery,
+    args: [ false ]
+  });
+</pre>
+
+
+<h1>Job Status</h1>
+<p>
+  The status of a job is made of 3 pieces of information
+</p>
+<ul>
+  <li>The job status code</li>
+  <li>Job logs</li>
+  <li>Job properties which are arbitrary key value pairs and also contain progress information</li>
+</ul>
+
+<p>
+  For convenience, the SDK provides a <b>getStatus</b> function which will fetch and return the full job status object with strong
+  typing. When getStatus is called several time, each call will fetch the most recent status, and new logs since the previous call.
+</p>
+
+<table>
+  <thead>
+    <tr><th>Status code</th><th>Description</th></tr>
+  </thead>
+  <tbody>
+    <tr><td><b>0</b></td><td>Being edited</td></tr>
+    <tr><td><b>2</b></td><td>Running: execution is in progress</td></tr>
+    <tr><td><b>3</b></td><td>Canceling: a cancel request was submitted and the job will be canceld as soon as possible</td></tr>
+    <tr><td><b>4</b></td><td>Canceled</td></tr>
+    <tr><td><b>5</b></td><td>Finished: the job has finished successfully and getResult can be called</td></tr>
+    <tr><td><b>6</b></td><td>Error: the job failed. Details about the error can be found in the logs</td></tr>
+    <tr><td><b>7</b></td><td>Pause pending: a pause request was submitted and the job will be paused as soon as possible</td></tr>
+    <tr><td><b>8</b></td><td>Pause: the job is paused</td></tr>
+    <tr><td><b>9</b></td><td>Purge pending: a purge request was submitted and the job will be purged as soon as possible</td></tr>
+  </tbody>
+</table>
+
+
+<h1>Job Progress</h1>
+<p>
+  The progress of a job is available as 2 integers: current and max which represent the current progression and max value for progression.
+  Both values are returned by the getStatus call as properties (i.e. <b>properties.progress.current</b> and <b>properties.progress.max</b>).
+  The SDK provides the <b>getProgress</b> function to retreive the progress as a percentage (and a valid number)
+</p>
+
+<pre class="code">
+  // Returns progress as a percentage in the [0..1] range
+  var progressPercent = job.getProgress();
+</pre>
+
+
+<h1>Job Result</h1>
+<p>
+  Typically, a client would call the getStatus method every few seconds to get updates on the progress. When a job is finished and successfull,
+  one can get the result using the <b>getResult</b> function
+</p>
+
+<pre class="code">
+  var result = await job.getResult();
+</pre>

package/package-lock.json

@@ -1,6 +1,6 @@
 {
   "name": "@adobe/acc-js-sdk",
-  "version": "1.1.15",
+  "version": "1.1.17",
   "lockfileVersion": 1,
   "requires": true,
   "dependencies": {

package/package.json

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

package/src/application.js

@@ -255,7 +255,7 @@ class XtkSchemaNode {
          * Returns a string of characters which specifies the editing type of the current node.
          * @type {string}
          */
-         this.editType = EntityAccessor.getAttributeAsString(xml, "editType");
+         this.editType = EntityAccessor.getAttributeAsString(xml, "edit");
 
         /**
          * Only on the root node, returns a string which contains the folder template(s). On the other nodes, it returns undefined.

package/src/cacheRefresher.js

@@ -146,7 +146,7 @@ governing permissions and limitations under the License.
         // Get last modified entities for the Campaign server and remove from cache last modified entities
         async _callAndRefresh() {
             const that = this;
-            const soapCall = this._client._prepareSoapCall("xtk:session", "GetModifiedEntities", true, this._connectionParameters._options.extraHttpHeaders);
+            const soapCall = this._client._prepareSoapCall("xtk:session", "GetModifiedEntities", true, true, this._connectionParameters._options.extraHttpHeaders);
 
             if (this._lastTime === undefined) {
                 const storedTime = this._refresherStateCache.get("time");
@@ -191,6 +191,7 @@ governing permissions and limitations under the License.
 
             // Do a soap call GetModifiedEntities instead of xtksession.GetModifiedEnties because we don't want to go through methodCache 
             // which might not contain the method GetModifiedEntities just after a build updgrade from a old version of acc 
+            // This is an internal SOAP call that cannot be intercepted by observers onBeforeCall / onAfterCall
             return this._client._makeSoapCall(soapCall)
                 .then(() => {
                     let doc = soapCall.getNextDocument();

package/src/campaign.js

@@ -30,7 +30,7 @@ const { Util } = require("./util.js");
   static CANNOT_GET_CREDENTIALS_PASSWORD(type)            { return new CampaignException(undefined, 400, 16384, `SDK-000002 Cannot get password for Credentials of type '${type}'`); }
   static INVALID_CONNECTION_OPTIONS(options)              { return new CampaignException(undefined, 400, 16384, `SDK-000003 Invalid options parameter (type '${typeof options}'). An object literal is expected`); }
   static INVALID_REPRESENTATION(representation, details)  { return new CampaignException(undefined, 400, 16384, `SDK-000004 Invalid representation '${representation}'.`, details); }
-  static CREDENTIALS_FOR_INVALID_EXT_ACCOUNT(name, type)  { return new CampaignException(undefined, 400, 16384, `SDK-000005 Cannot created connection parameters for external account '${name}': account type ${type} not supported`); }
+  static CREDENTIALS_FOR_INVALID_EXT_ACCOUNT(name, type)  { return new CampaignException(undefined, 400, 16384, `SDK-000005 Cannot create connection parameters for external account '${name}': account type ${type} not supported`); }
   static BAD_PARAMETER(name, value, details)              { return new CampaignException(undefined, 400, 16384, `SDK-000006 Bad parameter '${name}' with value '${value}'`, details); }
   static UNEXPECTED_SOAP_RESPONSE(call, details)          { return new CampaignException(     call, 500,   -53, `SDK-000007 Unexpected response from SOAP call`, details); }
   static BAD_SOAP_PARAMETER(call, name, value, details)   { return new CampaignException(     call, 400, 16384, `SDK-000008 Bad parameter '${name}' with value '${value}'`, details); }