@adobe/acc-js-sdk 1.1.15 → 1.1.16

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/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.16",
   "lockfileVersion": 1,
   "requires": true,
   "dependencies": {

package/package.json

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

package/src/client.js

@@ -36,6 +36,7 @@ const request = require('./transport.js').request;
 const Application = require('./application.js').Application;
 const EntityAccessor = require('./entityAccessor.js').EntityAccessor;
 const { Util } = require('./util.js');
+const { XtkJobInterface } = require('./xtkJob.js');
 const qsStringify = require('qs-stringify');
 
 /**
@@ -173,16 +174,7 @@ const clientHandler = (representation, headers, pushDownOptions) => {
                         return callContext;
 
                     // get Schema id from namespace (find first upper case letter)
-                    var schemaId = "";
-                    for (var i=0; i<namespace.length; i++) {
-                        const c = namespace[i];
-                        if (c >='A' && c<='Z') {
-                            schemaId = schemaId + ":" + c.toLowerCase() + namespace.substr(i+1);
-                            break;
-                        }
-                        schemaId = schemaId + c;
-                    }
-                    callContext.schemaId = schemaId;
+                    callContext.schemaId = Util.schemaIdFromNamespace(namespace);
 
                     const caller = function(thisArg, argumentsList) {
                         const callContext = thisArg["."];
@@ -1473,11 +1465,21 @@ class Client {
         const result = [];
         const schemaId = callContext.schemaId;
 
-        var schema = await that.getSchema(schemaId, "xml", true);
+        var entitySchemaId = schemaId;
+        if (schemaId === 'xtk:jobInterface')
+            entitySchemaId = callContext.entitySchemaId;
+
+        // Get the schema which contains the method call. Methods of the xtk:jobInterface interface are handled specificaaly
+        // because xtk:jobInterface is not actually a schema, but just an interface. In practice, it's used as an xtk template
+        // rather that an xtk inheritance mechanism
+        const methodSchemaId = schemaId === 'xtk:jobInterface' ? 'xtk:job' : schemaId;
+        var schema = await that.getSchema(methodSchemaId, "xml", true);
         if (!schema)
             throw CampaignException.SOAP_UNKNOWN_METHOD(schemaId, methodName, `Schema '${schemaId}' not found`);
         var schemaName = schema.getAttribute("name");
-        var method = that._methodCache.get(schemaId, methodName);
+
+        // Lookup the method to call
+        var method = that._methodCache.get(methodSchemaId, methodName);
         if (!method) {
             // first char of the method name may be lower case (ex: nms:seedMember.getAsModel) but the methodName 
             // variable has been capitalized. Make an attempt to lookup method name without capitalisation
@@ -1487,13 +1489,16 @@ class Client {
         }
         if (!method) {
             this._methodCache.put(schema);
-            method = that._methodCache.get(schemaId, methodName);
+            method = that._methodCache.get(methodSchemaId, methodName);
         }
         if (!method)
             throw CampaignException.SOAP_UNKNOWN_METHOD(schemaId, methodName, `Method '${methodName}' of schema '${schemaId}' not found`);
-        // console.log(method.toXMLString());
 
-        var urn = that._methodCache.getSoapUrn(schemaId, methodName);
+        // Compute the SOAP URN. Again, specically handle xtk:jobInterface as it's not a real schema. The actual entity schema
+        // would be available as the entitySchemaId property of the callContext
+        var urn = schemaId !== 'xtk:jobInterface' ? that._methodCache.getSoapUrn(schemaId, methodName)
+            : `xtk:jobInterface|${entitySchemaId}`;
+
         var soapCall = that._prepareSoapCall(urn, methodName, false, callContext.headers, callContext.pushDownOptions);
 
         // If method is called with one parameter which is a function, then we assume it's a hook: the function will return
@@ -1510,13 +1515,13 @@ class Client {
             if (!object)
                 throw CampaignException.SOAP_UNKNOWN_METHOD(schemaId, methodName, `Cannot call non-static method '${methodName}' of schema '${schemaId}' : no object was specified`);
 
-            const rootName = schemaId.substr(schemaId.indexOf(':') + 1);
+            const rootName = entitySchemaId.substr(entitySchemaId.indexOf(':') + 1);
             object = that._fromRepresentation(rootName, object, callContext.representation);
             // The xtk:persist#NewInstance requires a xtkschema attribute which we can compute here
             // Actually, we're always adding it, for all non-static methods
             const xmlRoot = object.nodeType === 9 ? object.documentElement : object;
             if (!xmlRoot.hasAttribute("xtkschema"))
-                xmlRoot.setAttribute("xtkschema", schemaId);
+                xmlRoot.setAttribute("xtkschema", entitySchemaId);
             soapCall.writeDocument("document", object);
         }
         const parametersIsArray = (typeof parameters == "object") && parameters.length;
@@ -1525,7 +1530,7 @@ class Client {
             var param = DomUtil.getFirstChildElement(params, "param");
             var paramIndex = 0;
             while (param) {
-                   const inout = DomUtil.getAttributeAsString(param, "inout");
+                const inout = DomUtil.getAttributeAsString(param, "inout");
                 if (!inout || inout=="in") {
                     const type = DomUtil.getAttributeAsString(param, "type");
                     const paramName = DomUtil.getAttributeAsString(param, "name");
@@ -1568,9 +1573,9 @@ class Client {
                             // Hack for workflow API. The C++ code checks that the name of the XML element is <variables>. When
                             // using xml representation at the SDK level, it's ok since the SDK caller will set that. But this does
                             // not work when using "BadgerFish" representation where we do not know the root element name.
-                            if (schemaId == "xtk:workflow" && methodName == "StartWithParameters" && paramName == "parameters")
+                            if (entitySchemaId == "xtk:workflow" && methodName == "StartWithParameters" && paramName == "parameters")
                                 docName = "variables";
-                            if (schemaId == "nms:rtEvent" && methodName == "PushEvent")
+                            if (entitySchemaId == "nms:rtEvent" && methodName == "PushEvent")
                                 docName = "rtEvent";
                             // Try to guess the document name. This is usually available in the xtkschema attribute
                             var xtkschema = EntityAccessor.getAttributeAsString(paramValue, "xtkschema");
@@ -1634,7 +1639,7 @@ class Client {
                         else if (type == "DOMDocument") {
                             returnValue = soapCall.getNextDocument();
                             returnValue = that._toRepresentation(returnValue, callContext.representation);
-                            if (schemaId === "xtk:queryDef" && methodName === "ExecuteQuery" && paramName === "output") {
+                            if (entitySchemaId === "xtk:queryDef" && methodName === "ExecuteQuery" && paramName === "output") {
                                 // https://github.com/adobe/acc-js-sdk/issues/3
                                 // Check if query operation is "getIfExists". The "object" variable at this point
                                 // is always an XML, regardless of the xml/json representation
@@ -1868,6 +1873,15 @@ class Client {
         const result = this._toRepresentation(doc);
         return result;
     }
+
+    /**
+     * Creates a Job object which can be used to submit jobs, retrieve status, logs and progress, etc.
+     * @param {Campaign.XtkSoapCallSpec} soapCallSpec the definition of the SOAP call
+     * @returns {Campaign.XtkJobInterface} a job
+     */
+    jobInterface(soapCallSpec) {
+        return new XtkJobInterface(this, soapCallSpec);
+    }
 }
 
 

package/src/util.js

@@ -133,6 +133,24 @@ class Util {
     }
     return obj;
   }
+
+  /**
+   * Get Schema id from namespace (find first upper case letter)
+   * @param {string} namespace a SDK namespace, i.e. xtkWorkflow, nmsDelivery, etc.
+   * @return {string} the corresponding schema id, i.e. xtk:workflow, nms:delivery, etc.
+   */
+  static schemaIdFromNamespace(namespace) {
+    var schemaId = "";
+    for (var i=0; i<namespace.length; i++) {
+        const c = namespace[i];
+        if (c >='A' && c<='Z') {
+            schemaId = schemaId + ":" + c.toLowerCase() + namespace.substr(i+1);
+            break;
+        }
+        schemaId = schemaId + c;
+    }
+    return schemaId;
+  }
 }
 
 /**