@adobe/acc-js-sdk 1.1.9 → 1.1.10

package/package.json

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

package/samples/005 - basics - persist.js

@@ -0,0 +1,160 @@
+/*
+Copyright 2022 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 { XtkCaster } = require("../src/xtkCaster.js");
+const utils = require("./utils.js");
+
+/**
+ * Basic samples illustrating the xtk:persist interface
+ */
+
+( async () => {
+  
+  await utils.sample({
+    title: "NewInstance",
+    labels: [ "xtk:persist", "Basics", "NewInstance", "CRUD" ],
+    description: `The "NewInstance" method creates a new instance of an entity in memory`,
+    code: async() => {
+      return await utils.logon(async (client, NLWS) => {
+        // Create a new delivery object
+        const delivery = client.NLWS.nmsDelivery.create({ label: "Test #1", messageType: "0" });
+        await delivery.newInstance();
+
+        // At this point, the delivery has been given an id (delivery.entity.id) and is ready to
+        // be persisted using client.NLWS.xtkSession.write or save
+        // Optionally, attributes can be set/changed at this point
+        delivery.$desc = "My description";
+        
+        // Now we're creating the delivery in the database
+        await client.NLWS.xtkSession.write(delivery);
+
+        // In order to update after creation, do not forget the "_operation=update" or the
+        // call will fail or create a duplicate
+        delivery._operation = "update";
+        delivery.label = "Test #4";
+        await delivery.save();
+
+        // Finally delete the object
+        delivery._operation = "delete";
+        await delivery.save();    
+      });
+    }
+  });
+  
+  await utils.sample({
+    title: "Duplicate",
+    labels: [ "xtk:persist", "Basics", "Duplicate", "CRUD" ],
+    description: `The "Duplicate" method creates a new instance of an entity in memory by duplicating an existing instance`,
+    code: async() => {
+      return await utils.logon(async (client, NLWS) => {
+
+        // Get the webApp operator id
+        const query = NLWS.xtkQueryDef.create({
+          schema: "xtk:operator", operation: "get",
+          select: { node: [ { expr: "@id" } ] },
+          where: { condition: [ { expr:`@name='webapp'` } ] }
+        });
+        const webAppOperator = await query.executeQuery();
+        const webAppOperatorId = XtkCaster.asLong(webAppOperator.id);
+
+        // Duplicate the webApp operator and name it 'alex'
+        const operator = client.NLWS.xtkOperator.create();
+        await operator.duplicate(`xtk:operator|${webAppOperatorId}`);
+        operator.name = "alex";
+        await operator.save();
+
+        // Change the operator name to 'Alexandre'
+        operator.entity.name = operator.entity.name + "andre";
+        operator._operation = "update";
+        await operator.save();
+      });
+    }
+  });
+
+  await utils.sample({
+    title: "Create a recipient",
+    labels: [ "xtk:persist", "Basics", "Write", "CRUD" ],
+    description: `The "Write" method creates or updates an entity`,
+    code: async() => {
+      return await utils.logon(async (client, NLWS) => {
+        await client.NLWS.xtkSession.write({ xtkschema:"nms:recipient", email: 'amorin@adobe.com' });
+      });
+    }
+  });
+
+  // Set recipient folder
+  await utils.sample({
+    title: "Set the folder of a recipient",
+    labels: [ "xtk:persist", "Basics", "Write", "CRUD" ],
+    description: `The "Write" method creates or updates an entity`,
+    code: async() => {
+      return await utils.logon(async (client, NLWS) => {
+
+        // Reserve an id and create a recipient with this id
+        const idList = XtkCaster.asArray(await client.NLWS.xtkSession.GetNewIdsEx(1, "XtkNewId"));
+        console.log(`Reserved ids: ${idList}`);
+        await client.NLWS.xtkSession.write({ xtkschema:"nms:recipient", id: idList[0], email: 'amorin@adobe.com' });
+
+        // Move to default folder
+        await client.NLWS.xtkSession.write({ 
+          xtkschema:"nms:recipient", 
+          id: idList[0], _operation:"update", 
+          folder: {
+            _operation: "none",
+            name: "nmsRootRecipient"
+          }
+        });
+      });
+    }
+  });
+
+  // Update folder label by key
+  await utils.sample({
+    title: "Update folder label",
+    labels: [ "xtk:persist", "Basics", "Write", "CRUD" ],
+    description: `The "Write" method creates or updates an entity`,
+    code: async() => {
+      return await utils.logon(async (client, NLWS) => {
+
+        // Create a folder
+        const name = 'acc_js_sdk_005';
+        console.log(`Creating a test folder with internal name '${name}'`);
+        const folder = client.NLWS.xtkFolder.create()
+        folder.name = name;
+        folder.label = 'Test folder for the ACC JS SDK (sample #5)';
+        await folder.save();
+
+        // Modify the folder label
+        console.log(`Modifying the folder label`);
+        await client.NLWS.xtkSession.write({ 
+          xtkschema: "xtk:folder", 
+          _operation: "update", name: name,
+          label: "Hello World",
+        });
+
+        // Loading the folder again
+        // Notice that changing the label has also triggered a change of the full name
+        const query = NLWS.xtkQueryDef.create({
+          schema: "xtk:folder", operation: "get",
+          select: { node: [ { expr: "@id" }, { expr: "@name" }, { expr: "@label" }, { expr: "@fullName" } ] },
+          where: { condition: [ { expr:`@name='${name}'` } ] }
+        });
+        const databaseFolder = await query.executeQuery();
+        console.log(`>> databaseFolder: ${JSON.stringify(databaseFolder)}`);
+
+        // Delete the folder
+        await client.NLWS.xtkSession.write({ xtkschema: "xtk:folder", _operation: "delete", name: name });
+      });
+    }
+  });
+  
+})();
+

package/src/application.js

@@ -608,6 +608,11 @@ class XtkSchemaNode {
          */
         this.packageStatus = PACKAGE_STATUS[this.packageStatusString];
 
+        /**
+         * Returns a string (a schema id) which indicates the custom/extended entity, attribute belongs to.
+         */
+        this.belongsTo = EntityAccessor.getAttributeAsString(xml, "belongsTo");
+
          // Children (elements and attributes)
         const childNodes = [];
         for (const child of EntityAccessor.getChildElements(xml)) {

package/src/client.js

@@ -71,8 +71,24 @@ const { Util } = require('./util.js');
  * @memberof Campaign
  */
 const xtkObjectHandler = {
+    set: function(callContext, prop, value) {
+        const object = callContext.object;
+        object[prop] = value;
+    },
+
     get: function(callContext, methodName) {
-        if (methodName == ".") return callContext;
+        if (methodName == ".") 
+            return callContext;
+        if (methodName === "__xtkProxy")
+            return true;
+        if (methodName === "save") {
+            return async () => {
+                return callContext.client.NLWS.xtkSession.write(callContext.object);
+            };
+        }
+        if (methodName === "entity") {
+            return callContext.object;
+        }
 
         const caller = function(thisArg, argumentsList) {
             const callContext = thisArg["."];
@@ -149,7 +165,8 @@ const clientHandler = (representation, headers, pushDownOptions) => {
                         for (let h in pushDownOptions) callContext.pushDownOptions[h] = pushDownOptions[h];
                     }
 
-                    if (methodName == ".") return callContext;
+                    if (methodName == ".") 
+                        return callContext;
 
                     // get Schema id from namespace (find first upper case letter)
                     var schemaId = "";
@@ -187,7 +204,8 @@ const clientHandler = (representation, headers, pushDownOptions) => {
 
                     if (methodName == "create") {
                         return function(body) {
-                            callContext.object = body;
+                            callContext.object = body || {}; // supports empty bodies
+                            if (!callContext.object.xtkschema) callContext.object.xtkschema = callContext.schemaId;
                             return new Proxy(callContext, xtkObjectHandler);
                         };
                     }
@@ -1380,16 +1398,20 @@ class Client {
      * @returns {XML.XtkObject}  the schema definition, as either a DOM document or a JSON object
      */
     async getSchema(schemaId, representation, internal) {
-        var that = this;
-        var entity = that._entityCache.get("xtk:schema", schemaId);
+        var entity = this._entityCache.get("xtk:schema", schemaId);
         if (!entity) {
-          entity = await that.getEntityIfMoreRecent("xtk:schema", schemaId, "xml", internal);
+          entity = await this.getEntityIfMoreRecent("xtk:schema", schemaId, "xml", internal);
           if (entity) {
-            that._entityCache.put("xtk:schema", schemaId, entity);
-            that._methodCache.put(entity);
+            const impls = DomUtil.getAttributeAsString(entity, "implements");
+            if (impls === "xtk:persist" && schemaId !== "xtk:session" && schemaId !== "xtk:persist") {
+                // Ensure xtk:persist is present by loading the xtk:session schema
+                await this.getSchema("xtk:session", "xml", true);
+            }
+            this._entityCache.put("xtk:schema", schemaId, entity);
+            this._methodCache.put(entity);
           }
         }
-        entity = that._toRepresentation(entity, representation);
+        entity = this._toRepresentation(entity, representation);
         return entity;
     }
 
@@ -1481,9 +1503,13 @@ class Client {
 
             const rootName = schemaId.substr(schemaId.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);
             soapCall.writeDocument("document", object);
         }
-
         const parametersIsArray = (typeof parameters == "object") && parameters.length;
         const params = DomUtil.getFirstChildElement(method, "parameters");
         if (params) {
@@ -1494,10 +1520,12 @@ class Client {
                 if (!inout || inout=="in") {
                     const type = DomUtil.getAttributeAsString(param, "type");
                     const paramName = DomUtil.getAttributeAsString(param, "name");
-                    const paramValue = parametersIsArray ? parameters[paramIndex] : parameters;
+                    let paramValue = parametersIsArray ? parameters[paramIndex] : parameters;
                     paramIndex = paramIndex + 1;
                     if (type == "string")
                         soapCall.writeString(paramName, XtkCaster.asString(paramValue));
+                    else if (type == "primarykey")
+                        soapCall.writeString(paramName, XtkCaster.asString(paramValue));
                     else if (type == "boolean")
                         soapCall.writeBoolean(paramName, XtkCaster.asBoolean(paramValue));
                     else if (type == "byte")
@@ -1516,22 +1544,35 @@ class Client {
                         soapCall.writeDate(paramName, XtkCaster.asDate(paramValue));
                     else if (type == "DOMDocument" || type == "DOMElement") {
                         var docName = undefined;
-                        // 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")
-                            docName = "variables";
-                        if (schemaId == "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");
-                        if (!xtkschema) xtkschema = paramValue["@xtkschema"];
-                        if (xtkschema) {
+                        let representation = callContext.representation;
+                        if (paramValue.__xtkProxy) {
+                            // A xtk proxy object is passed as a parameter. The call context contains the schema so we
+                            // can use it to determine the XML document root (docName)
+                            const paramValueContext = paramValue["."];
+                            paramValue = paramValueContext.object;
+                            const xtkschema = paramValueContext.schemaId;
                             const index = xtkschema.indexOf(":");
-                            docName = xtkschema.substr(index+1);
+                            docName = xtkschema.substring(index+1);
+                            representation = paramValueContext.representation; // xtk proxy may have it's own representation
+                        }
+                        else {
+                            // 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")
+                                docName = "variables";
+                            if (schemaId == "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");
+                            if (!xtkschema) xtkschema = paramValue["@xtkschema"];
+                            if (xtkschema) {
+                                const index = xtkschema.indexOf(":");
+                                docName = xtkschema.substring(index+1);
+                            }
+                            if (!docName) docName = paramName; // Use te parameter name as the XML root element
                         }
-                        if (!docName) docName = paramName; // Use te parameter name as the XML root element
-                        var xmlValue = that._fromRepresentation(docName, paramValue, callContext.representation);
+                        var xmlValue = that._fromRepresentation(docName, paramValue, representation);
                         if (type == "DOMDocument")
                             soapCall.writeDocument(paramName, xmlValue);
                         else
@@ -1564,6 +1605,8 @@ class Client {
                         var returnValue;
                         if (type == "string")
                             returnValue = soapCall.getNextString();
+                        else if (type == "primarykey")
+                            returnValue = soapCall.getNextPrimaryKey();
                         else if (type == "boolean")
                             returnValue = soapCall.getNextBoolean();
                         else if (type == "byte")

package/src/methodCache.js

@@ -90,33 +90,44 @@ class MethodCache extends Cache {
         var impls = DomUtil.getAttributeAsString(schema, "implements");
         var root = DomUtil.getFirstChildElement(schema);
         while (root) {
-            var schemaId;
-            var soapUrn;
-
+            let schemaId;
             if (root.nodeName == "interface") {
-                const itfName = namespace + ":" +  DomUtil.getAttributeAsString(root, "name");
-                if (impls === itfName) {
-                    schemaId = namespace + ":" + name;
-                    soapUrn = itfName;
-                }
+                const nodeName = DomUtil.getAttributeAsString(root, "name");
+                schemaId = `${namespace}:${nodeName}`;
             }
             else if (root.nodeName == "methods") {
-                schemaId = namespace + ":" + name;
-                soapUrn = schemaId;
+                schemaId = `${namespace}:${name}`;
             }
-
             if (schemaId) {
                 var child = DomUtil.getFirstChildElement(root, "method");
                 while (child) {
                     const methodName = DomUtil.getAttributeAsString(child, "name");
-                    const cached = { method: child, urn: soapUrn };
+                    const cached = { method: child, urn: schemaId };
                     super.put(schemaId, methodName, cached);
-                    super.put(soapUrn, methodName, cached); /// version 0.1.23: cache the method in both the schema id and interface id form compatibility reasons
                     child = DomUtil.getNextSiblingElement(child, "method");
                 }
             }
             root = DomUtil.getNextSiblingElement(root);
         }
+
+        // If the schema implements an interface, then add the interface methods to the schema
+        // methods in the cache, using the "<interface>|<schemaId>" urn
+        // example: xtk:session implements xtk:persist, and therefore will have xtk:persist methods
+        // under the urn "xtk:persist|xtk:session"
+        if (impls) {
+            const schemaId = `${namespace}:${name}`;
+            const prefix = `${impls}#`;
+            const urn = `${impls}|${schemaId}`;
+            const keys = Object.keys(this._cache);
+            for (const key of keys) {
+                if (key.startsWith(prefix)) {
+                    let cached = this._cache[key].value;
+                    cached = { method: cached.method, urn: urn };
+                    const methodName = DomUtil.getAttributeAsString(cached.method, "name");
+                    super.put(schemaId, methodName, cached);
+                }
+            }
+        }
     }
 
     /**

package/src/soap.js

@@ -356,13 +356,25 @@ class SoapMethodCall {
      * 
      * @returns {string} the string result value
      */
-    getNextString() {
+     getNextString() {
         this._checkTypeMatch("xsd:string");
         var value = DomUtil.elementValue(this.elemCurrent);
         this.elemCurrent = DomUtil.getNextSiblingElement(this.elemCurrent);
         return value;
     }
 
+    /**
+     * Extracts the next result value as a primary key string
+     * 
+     * @returns {string} the primary key string result value
+     */
+     getNextPrimaryKey() {
+        this._checkTypeMatch("xsd:primarykey");
+        var value = DomUtil.elementValue(this.elemCurrent);
+        this.elemCurrent = DomUtil.getNextSiblingElement(this.elemCurrent);
+        return value;
+    }
+
     /**
      * Extracts the next result value as a boolean
      * 

package/src/xtkCaster.js

@@ -58,6 +58,7 @@ const { Util } = require('./util.js');
 |     timespan | 14 |  number | A timespan, in seconds
 |      boolean | 15 | boolean | boolean value, defaultint to false. Cannot be null |
 |        array |    |   Array | a array or a collection
+|   primarykey |    |  string | A primary key is serialized with format <schemaId>|<keyField>[|<keyField>[...]]
 
  * @typedef {(0|''|6|'string'|'int64'|12|13|'memo'|'CDATA'|1|'byte'|2|'short'|3|'long'|15|'boolean'|4|5|'float'|'double'|7|'datetime'|'datetimetz'|'datetimenotz'|10|'date'|14|'timespan'|'array')} XtkType
  * @memberof Campaign
@@ -94,6 +95,7 @@ class XtkCaster {
             case "string":
             case "uuid":
             case "int64":
+            case "primarykey":
                 return "stringValue";
             case 12:            // FIELD_MEMO
             case 13:            // FIELD_MEMOSHORT
@@ -198,6 +200,9 @@ class XtkCaster {
             case "timespan": {
                 return this.asTimespan(value);
             }
+            case "primarykey": {
+                return this.asPrimaryKey(value);
+            }
             default: {
                 throw CampaignException.BAD_PARAMETER("type", type, `Cannot convert value type='${type}', value='${value}'`);
             }
@@ -218,7 +223,21 @@ class XtkCaster {
                 return "";  // Invalid JavaScript date
             return value.toISOString();
         }
-        if ((typeof value) == "object") return "";
+        if ((typeof value) == "object") {
+            if (XtkCaster.isPrimaryKey(value)) {
+                let result = value.schemaId;
+                for (let i=0; i<value.values.length; i++) {
+                    result = result + "|";
+                    let item = value.values[i];
+                    if (item === null || item === undefined) continue;
+                    if (typeof item !== "string") item = XtkCaster.asString(item);
+                    const escaped = item.replace(/\|/g, "\\|").replace(/\"/g, "\\\""); // escape | and " chars
+                    result = result + escaped;
+                }
+                return result;
+            }
+            return "";
+        }
         return value.toString();
     }
 
@@ -430,6 +449,35 @@ class XtkCaster {
         var timespan = XtkCaster.asLong(value);
         return timespan;
     }
+    
+    /**
+     * Convert a raw value into an primary key object. A  primary key is serialized with format <schemaId>|<keyField>[|<keyField>[...]]
+     *
+     * @param {*} value is the raw value to convert
+     * @return {PrimaryKey} a primary key
+     */
+     static asPrimaryKey(value) {
+        if (value === null || value === undefined) return undefined;
+        if (this.isPrimaryKey(value)) return value;
+        value = value.toString();
+        let index = value.indexOf('|');
+        if (index <= 0) return undefined; // no schema id or empty schema id
+        const primaryKey = {
+            schemaId: value.substring(0, index),
+            values: []
+        };
+        value = value.substring(index+1) + "|";
+        let start = 0;
+        for(var i=0; i<value.length; i++) {
+            const c = value[i];
+            if (c === '\\') { i = i + 1; continue; } // escaped char
+            if (c === '|') {
+                primaryKey.values.push(value.substring(start, i).replace(/\\/g, ""));
+                start = i + 1;
+            }
+        }
+        return primaryKey;
+    }
 
     /**
      * Tests if a given type is a date or time type
@@ -445,7 +493,7 @@ class XtkCaster {
      * @param {string|number} type the type name
      * @returns {boolean} true if the type is a string type
      */
-     static isStringType(type) {
+    static isStringType(type) {
         return type === "string" || type === "memo" || type === 6 || type === 12 || type === 13 || type === "blob" || type === "html" || type === "CDATA";
     }
 
@@ -454,9 +502,19 @@ class XtkCaster {
      * @param {string|number} type the type name
      * @returns {boolean} true if the type is a numeric type
      */
-     static isNumericType(type) {
+    static isNumericType(type) {
         return type === "byte" || type === 1 || type === "short" || type === 2 || type === "int" || type === "long" || type === 3 || type === "float" || type === 4 || type === "double" || type === 5 || type === "timespan" || type === 14;
     }
+
+    /**
+     * Tests if an object is a primary key, i.e. has a schemaId and a array of values
+     * @param {*} value the object to test
+     * @returns true or false depending on whether the object is a primary key or not
+     */
+    static isPrimaryKey(value) {
+        if (!value) return false;
+        return !!(value.schemaId && value.values && Util.isArray(value.values));
+    }
 }
 
 

package/test/application.test.js

@@ -1270,6 +1270,29 @@ describe('Application', () => {
             });
         });
 
+        describe("belongsTo", () => {
+            
+            it("Should extract belongsTo", async () => {
+                var xml = DomUtil.parse(`<schema namespace='nms' name='delivery'>
+                    <element name='delivery' label='Delivery'>
+                        <attribute belongsTo="nms:deliveryOperation" defOnDuplicate="true" enum="sandboxStatus" label="Status of inclusion in the provisional calendar" name="sandboxStatus" sqlname="iSandboxStatus" type="byte"/>
+                        <attribute belongsTo="cus:delivery" label="" length="255" name="hello" sqlname="sHello" type="string"/>
+                        <element advanced="true" desc="Memo field containing data stored as XML" label="XML memo" name="data" sqlname="mData" type="memo"/>
+                    </element>
+                </schema>`);
+                var schema = newSchema(xml);
+
+                var node = await schema.root.findNode("@sandboxStatus");
+                expect(node).toMatchObject({ name:"@sandboxStatus", belongsTo:"nms:deliveryOperation", childrenCount:0 });
+
+                var node = await schema.root.findNode("@hello");
+                expect(node).toMatchObject({ name:"@hello", belongsTo:"cus:delivery", childrenCount:0 });
+
+                var node = await schema.root.findNode("data");
+                expect(node).toMatchObject({ name:"data", belongsTo:"", childrenCount:0 });
+            });
+        });
+
         describe("Links", () => {
             it("Should find link node", async () => {
                 var xml = DomUtil.parse(`<schema namespace='nms' name='recipient'>

package/test/caches.test.js

@@ -267,7 +267,7 @@ describe('Caches', function() {
             assert.ok(found !== null && found !== undefined);
             assert.strictEqual(found.nodeName, "method");
             assert.strictEqual(found.getAttribute("name"), "Write");
-            assert.strictEqual(urn, "xtk:persist");
+            assert.strictEqual(urn, "xtk:persist|xtk:session");
 
             // For compatibility reasons (SDK versions earlier than 0.1.23), keep the Write method on the interface too
             found = cache.get("xtk:persist", "Write");