@adobe/acc-js-sdk 1.0.7 → 1.1.0

package/README.md

@@ -3,6 +3,7 @@
 This is a node.js SDK for Campaign API. It exposes the Campaign API exactly like it is used inside Campaign using the NLWS notation.
 
 
+
 # Change log
 
 See the [Change log](./CHANGELOG.md) for more information about the different versions, changes, etc.
@@ -470,7 +471,12 @@ More dynamic conversions can be achieved using the `as` function. See the types
 
 ```js
 stringValue = XtkCaster.as(anyValue, 6);
-````
+```
+
+In addition, the following helpers are available
+* `XtkCaster.isTimeType` to test if a data type is a date, time or timestamp
+* `XtkCaster.isStringType` to test if a data type is a string type (string, memo, etc.)
+* `XtkCaster.isNumericType` to test if a data type is a numeric type
 
 
 ## DOM helpers
@@ -1013,6 +1019,8 @@ It's common to use variables in query conditions. For instance, in the above exa
 To prevent xtk ingestions vulnerabilities, you should not concatenate strings and write code such as expr: "@name = '" + name + "'": if the value of the name 
 parameter contains single quotes, your code will not work, but could also cause vulnerabilities.
 
+### sdk.escapeXtk
+
 The `sdk.escapeXtk` can be used to properly escape string litterals in xtk expressions. The function will also surround the escaped value with single quotes.
 
 You can use string concatenation like this. Note the lack of single quotes around the value.
@@ -1039,6 +1047,35 @@ This can also be used to escape other data types such as timestamps
 will return `{ expr: "@lastModified > = #2021-07-07T10:03:33.332Z# }`
 
 
+### sdk.escapeForLike
+
+This function escapes values so that they can be used in SQL or XTK like conditions. For example a search term "term" can be escaped as follows to implement a search conditions
+
+```
+    expr: `Lower([${xpath}]) LIKE '%${sdk.escapeForLike(term)}%'`,
+```
+
+### sdk.expandXPath & sdk.unexpandXPath
+
+In Campaign, xpaths are used to access attributes of entities. When XPaths are used in XTK expressions, there can be ambiguities, for instance, in the expression "country/@name", is "country/@name" a xpath or are we dividing the variable country by the value of the attribute @name?
+
+Amibiguity can be resolved by "expanding" the xpath from "country/@name" to "[country/@name]". The square brackets indicate an xpath.
+
+```
+    const expandedXPath = sdk.expandXPath(xpath);
+    const unexpandedXPath = sdk.unexpandXPath(expandedXPath);
+```
+
+### xtkConstText
+
+This function allows to convert literal values to xtk text constants, providing correct serialization. For instance, text constants will be quoted with single quotes, timestamps with the "#" character, etc.
+
+```
+    expect(sdk.xtkConstText("Hello", "string")).toBe("'Hello'");
+    expect(sdk.xtkConstText(-42.3, "double")).toBe("-42.3");
+    expect(sdk.xtkConstText("2022-02-15T09:49:04.000Z", "datetime")).toBe("#2022-02-15T09:49:04.000Z#");
+```
+
 
 ## Pagination
 Results can be retrieved in different pages, using the `@lineCount` and `@startLine` attributes. For instance, retrieves profiles 3 and 4 (skip 1 and 2)
@@ -1299,23 +1336,24 @@ The `application` object can be obtained from a client, and will mimmic the Camp
 
 | Attribute/Method | Description |
 |---|---|
-| buildNumber | The server build number
-| 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
-| getSchema(schemaId) | Get a schema by id (see the Schemas section below)
-| hasPackage(name) | Tests if a package is installed or not
+| **buildNumber** | The server build number
+| **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
+| async **getSchema**(schemaId) | Get a schema by id (see the Schemas section below)
+| async **getEnumeration**(enumerationName, schemaOrSchemaId) | Get an enumeration
+| **hasPackage**(name) | Tests if a package is installed or not
 
 
 The `CurrentLogin` object has the following attributes / functions
 
 | Attribute/Method | Description |
 |---|---|
-| id | the internal id (int32) of the operator
-| login | the login name of the operator
-| computeString | A human readable name for the operator
-| timezone | The timezone of the operator
-| rights | An array of strings describing the rights of the operators
+| **id** | the internal id (int32) of the operator
+| **login** | the login name of the operator
+| **computeString** | A human readable name for the operator
+| **timezone** | The timezone of the operator
+| **rights** | An array of strings describing the rights of the operators
 
 # Schemas
 
@@ -1356,85 +1394,264 @@ The Schema API closely mimmics the Campaign server side API : https://docs.adobe
 
 * The `XtkSchema` and associated classes (`XtkSchemaNode`, `XtkSchemaKey`, `XtkEnumeration` and `XtkEnumerationValue`) are all immutable. There are currently no API to create schemas dynamically
 * Not all methods and functions are implemented
+* Several methods are asynchronous because they may require a server round trip to fetch schemas, etc.
 * There could be slight differences in usage due to Campaign server side JavaScript using some E4X specific constructs to iterate over collections (ex: for each(...)) which are not available in standard JavaScript environments
 
 The entry point is the application object. Obtain a schema from its id:
 
 ```js
 const application = client.application;
-const schema = application.getSchema("nms:recipient");
+const schema = await application.getSchema("nms:recipient");
 ```
 
 This return a schema object of class `XtkSchema`
 
 
-### XtkSchema / XtkSchemaNode
-
-| Attribute/Method | | Description |
-|---|---|---|
-| schema | | The schema to which this node belongs
-| id | schema | For schemas, the id of the schema. For instance "nms:recipient"
-| namespace | schema | For schemas, the namespace of the schema. For instance "nms"
-| name |  | The name of the node (internal name)
-| label | | The label (i.e. human readable, localised) name of the node.
-| labelSingular | schema | The singular label (i.e. human readable, localised) name of the schema. The label of a schema is typically a plural.
-| description | | A long, human readable, description of the node
-| img | | The name of the image (if any) corresponding to the node
-| type | | The data type of the node, for instance "string", "long", etc.
-| length | | For string nodes, the maximum length of the node value
-| ref | |
-| isAttribute | | Indicates if the node is an attribute (true) or an element (false)
-| children | | A map of children of the node, indexed by name. Names never contain the "@" sign, even attribute names
-| childrenCount | | Number of children nodes
-| parent | | The parent node. Will be null for schema nodes
-| isRoot | | Indicates if the node is the root node of a schema, i.e. the first child of the schema node, whose name matches the schema name
-| userDescription | |
-| keys | | A map of keys in this node, indexed by key name. Map values are of type `XtkSchemaKey`
-| nodePath  | | The absolute full path of the node
-| hasChild(name) | | Tests if the node has a child wih the given name
-| findNode(path) | Find a child node using a xpath
-| isLibrary | schema | For schemas, indicates if the schema is a library
-| mappingType | schema | Schema mapping type. Usually "sql"
-| xml | schema | The XML (DOM) corresponding to this schema
-| root | schema | The schema root node, if there is one. A reference to a `XtkSchemaNode`
-| enumerations | schema | Map of enumerations in this schema, indexed by enumeration name. Values are of type `XtkEnumeration`
+### Iterating over collections
+The metadata SDK closely mimmics the Campaign API, but provides convenience functions to access collections of objects, such as the children of a node, the values of an enumeration, etc. using an `ArrayMap` structure which allows access as both an array and a map.
+
+Access as a map. Child elements can be accessed with their names, as if it was a JavaScript map. For instance, accessing the gender of a recipient. This method is kept as a compatibility layer with the legacy API and older versions of the SDK but is deprecated / discouraged. The reason is that there are schemas which have attribut names such as "length", or element names such as "forEach" which collide with JavaScript objects.
+```js
+const schema = await client.application.getSchema("nms:recipient");
+const enumerations = schema.enumerations;
+// deprecated, discouraged
+expect(enumerations.gender.label).toBe("Gender");
+```
+
+Instead, prefer the `get` function which can retreive any enumeration value
+```js
+const schema = await client.application.getSchema("nms:recipient");
+const enumerations = schema.enumerations;
+expect(enumerations.get("gender").label).toBe("Gender");
+```
+
+Elements can also be accessed as an array. In this example, we are iterating over the enumerations of a schema
+```js
+const schema = await client.application.getSchema("nms:recipient");
+const enumerations = schema.enumerations;
+for (let i=0; i<enumerations.length; i++) { 
+    const enumeration = enumerations[i];
+}
+```
+
+Note that this assumes that there is no enumeration called "length" which will override the "length" attribute. Schemas, schema elements, and sql schemas have attributes named "length", but they are attributes, and will therefore be named "@length" in the metadata API. There is no  element named "length" in out-of-the-box schemas.
+
+The ArrayMap also behaves like an iterator and works fine with the `for...of` syntax
+```js
+const schema = await client.application.getSchema("nms:recipient");
+const enumerations = schema.enumerations;
+for (const enumeration of enumerations) { 
+    ...
+}
+```
+
+For convenience, the `map` and `forEach`, `find`, `filter`, `get`, and `flatMap` methods are also available and behave as expected:
+
+```js
+const schema = await client.application.getSchema("nms:recipient");
+// comma separated list of enumerations
+const enumerations = schema.enumerations.map(e => e.name).join(',');
+```
+
+```js
+const schema = await client.application.getSchema("nms:recipient");
+schema.enumerations.forEach(e => { ... });
+```
+
+The `for...in` loop is also supported but deprecated/discouraged as it may return incorrect results for collections having items whose key collide with javaScript properties (such as length, map, forEach, etc.). Use a `for...of` construcr instead, or the `map` or `forEach` functions.
+```js
+const schema = await client.application.getSchema("nms:recipient");
+// deprecated, discouraged
+for (const key in schema.enumerations) {
+    ...
+}
+```
+
+## Navigating schemas
+The schema API is useful to quickly navigate in the schema hierarchy. Here are a few examples
+
+Get the label of the email attribute of the nms:recipient schema
+```js
+const schema = await application.getSchema("nms:recipient");
+const email = await schema.root.findNode("@email");
+console.log(email.label);
+```
+
+The `findNode` function follows links and references
+* The function now supports `ref` nodes. Ref nodes are schema nodes having a `ref` property which is a reference to another node, possibly in a different schema. 
+    * If the xpath passed to the function ends with a ref node, the ref node itself will be returned. We're not following the reference. You can use the `refTarget` method to explicitely follow the reference
+    * If the xpath traverse intermediate nodes which are ref nodes, the `findNode` method will follow the reference. For instance, the start activity in a workflow is a reference. Finding the xpath "start/@img" will follow the start reference and find the @img attribute from there
+
+* Support for links. If the xpath parameter contains links, `findNode` will follow the link 
+target with the same rules as for reference nodes. To get the target of a link, use the `linkTarget` method instead of `refTarget`.
+
+
+For insance, you can get the country of a recipient who clicked in an email. This call follows the link from nms:broadLogRcp to nms:recipient and then from nms:recipient to nms:country, returning the country isoA3 attribute.
+```js
+const schema = await application.getSchema("nms:broadLogRcp");
+const node = await schema.root.findNode("recipient/country/@isoA3");
+```
+
+The same syntax can be used for reference nodes. For instance, getting the attributes of the start activity of a workflow:
+```js
+const schema = await application.getSchema("xtk:workflow");
+const node = await schema.root.findNode("start/@name");
+```
+
+In order to actually iterate over the children, things are a little bit more complicated
+```js
+const schema = await application.getSchema("xtk:workflow");
+const start = await schema.root.findNode("start");
+// start is the ref node, not the target of the ref. One need to explicitely
+// follow the ref in order to get the list of children
+const target = await start.refTarget();
+target.children.forEach(child => ... );
+```
+
+To get the root node of the target of a link, use the `linkTarget` function
+```js
+const schema = await application.getSchema("nms:broadLogRcp");
+const node = await schema.root.findNode("recipient/country");
+// node is the country link, not the root node of the nms:country schema
+const root = await node.linkTarget();
+// root is the root node of the nms:country schema
+```
+
+
+### XtkSchema 
+
+| Attribute | Description |
+|---|---|
+| **id** | The id of the schema. For instance "nms:recipient"
+| **namespace** | The namespace of the schema. For instance "nms"
+| **name** | The name of the schema (internal name)
+| **label** | The label (i.e. human readable, localised) name of the node.
+| **labelSingular** | The singular label (i.e. human readable, localised) name of the schema. The label of a schema is typically a plural.
+| **isLibrary** | For schemas, indicates if the schema is a library
+| **mappingType** |Schema mapping type. Usually "sql"
+| **md5** | The MD5 code of the schema in the form of a hexadecimal string
+| **xml** | The XML (DOM) corresponding to this schema.<br>Note: this attribute is not available in the JS SDK.
+| **root** | The schema root node, if there is one. A reference to a `XtkSchemaNode`
+| **enumerations** | Map of enumerations in this schema, indexed by enumeration name. Values are of type `XtkEnumeration`
+| **userDescription** | The description of the schema in the form of a string.
+
+A schema is also a `XtkSchemaNode` and the corresponding properties/methods are also availale.
+
+### XtkSchemaNode
+
+| Attribute | Description |
+|---|---|
+| **children** | A array/map of children of the node. See note on the ArrayMap structure below
+| **dataPolicy** | Returns a string of characters which provides the data policy of the current node.
+| **description** | A long, human readable, description of the node
+| **editType** |Returns a string of characters which specifies the editing type of the current node.
+| **enum** | The name of the enumeration for the node, or an empty string if the node does node have an enumeration. See `enumeration()` method to get the corresponding `XtkSchemaNode`
+| **enumerationImage** | Returns the name of the image of the current node in the form of a string of characters.
+| **folderModel** |Only on the root node, returns a string which contains the folder template(s). On the other nodes, it returns undefined.
+| **image**  | Returns the name of the image in the form of a string of characters.
+| **img** | Returns the name of the image in the form of a string of characters. (alias to `image` property)
+| **integrity** | Returns the link integrity type.
+| **keys** | A array/map of keys in this node, indexed by key name. Map values are of type `XtkSchemaKey`
+| **hasEnumeration** | Returns a boolean which indicates whether the value of the current node is linked to an enumeration.
+| **childrenCount** | Number of children nodes
+| **hasSQLTable** | Returns a boolean which indicates whether the current node is linked to an SQL table.
+| **hasUserEnumeration** | Returns a boolean which indicates whether the value of the current node is linked to a user enumeration.
+| **schema** | The schema (`XtkSchema`) to which this node belongs
+| **isAdvanced** | Returns a boolean which indicates whether the current node is advanced or not.
+| **isAnyType** | Returns a boolean which indicates whether the current node is ordinary.
+| **isAttribute** | Indicates if the node is an attribute (true) or an element (false)
+| **isAutoIncrement** | Returns a boolean which indicates whether the value of the current node is incremented automatically.
+| **isAutoPK** | Returns a boolean which indicates whether the current node is a primary key.
+| **isAutoUUID** | Yes | No | Returns a boolean which indicates whether the current node is an automatic UUID
+| **isAutoStg** | Yes | No | Returns a boolean which indicates whether the schema is a staging schema
+| **isBlob** | Returns a boolean which indicates whether the current node is a BLOB.
+| **isCalculated** | Returns a boolean which indicates whether the value of the current node is the result of a calculation. Note that compute strings are not considered as calculated attributes.
+| **isCDATA** | Returns a boolean which indicates whether the current node is mapped from CDATA type XML.
+| **isCollection** | Returns a boolean which indicates whether the current node is a collection of sub-elements and/or attributes. This is an alias to `unbound` and `isUnbound` properties.
+| **isDefaultOnDuplicate** | Returns a boolean. If the value added is vrai, during record deduplication, the default value (defined in defaultValue) is automatically reapplied during recording.
+| **isElementOnly** | Returns a boolean which indicates whether the current node is a logical sub-division of the schema.
+| **isExternalJoin** | True if the node is a link and if the join is external.
+| **isLink** | Returns a boolean which indicates whether the node is a link.
+| **isMappedAsXML** | Returns a boolean which indicates whether the node is an XML mapping.
+| **isMemo** | Returns a boolean which indicates whether the current node is mapped by a Memo.
+| **isMemoData** | Returns a boolean which indicates whether the current node is mapped by a MemoData.
+| **isNotNull** | Returns a boolean which indicates whether or not the current node can take the null value into account.
+| **isRequired** | Returns a boolean which indicates whether or not the value of the current node is mandatory.
+| **isRoot** | Indicates if the node is the root node of a schema, i.e. the first child of the schema node, whose name matches the schema name
+| **isSQL** | Returns a boolean which indicates whether the current node is mapped in SQL.
+| **isTemporaryTable** | Returns a boolean indicating whether the table is a temporary table. The table will not be created during database creation.
+| **unbound** | Returns a boolean which indicates whether the current node has an unlimited number of children of the same type.
+| **joins** | Element of type "link" has an array of XtkJoin. See `joinNodes` method.
+| **label** | The label (i.e. human readable, localised) name of the node.
+| **name** | The name of the node (internal name)
+| **nodePath**  | The xpath of the node
+| **parent** | The parent node (a `XtkSchemaNode` object). Will be null for schema nodes
+| **PKSequence** | Returns a character string that provides the name of the sequence to use for the primary key.
+| **packageStatus** | Returns a number that gives the package status.
+| **packageStatusString** |  Returns a string that gives the package status ("never", "always", "default", or "preCreate").
+| **revLink** | Returns the name of the reverse link in the link target schema. See `reverseLink` method to get the actual reverse link object
+| **SQLName** | The SQL name of the field. The property is an empty string if the object isn't an SQL type field.
+| **SQLTable** | The SQL name of the table. The property is an empty string if the object isn't the main element or if schema mapping isn't of SQL type.
+| **size** | For string nodes, the maximum length of the node value. Alias to `length`.
+| **length** | For string nodes, the maximum length of the node value. Alias to `size`.
+| **target** | A string corresponding to the target of a link. Note that in the SDK, this is a string, whereas in the JS API, this is the actual target node. Because the SDK is async. Use `linkTarget` to get the target node of a link.
+| **type** | The data type of the node, for instance "string", "long", etc.
+| **userEnumeration** | Returns a string of characters which is the name of the user enumeration used by the current node.
+| **ref** | Some nodes are only references to other nodes. There are 2 kind of references. Local references are simply a xpath in the current schema (starting from the schema itself, and not the schema root). Fully qualified references are prefixed with a schema id. The target node can be accessed with the `refTarget` funtion.
+| **isMappedAsXml** | Is the field mapped as XML?
+
+
+
+| Method | Description |
+|---|---|
+| async **findNode** | Find a child node using a xpath. This function follows links and references if necessary and will dynamically fetch/cache necessary schemas. 
+| async **refTarget** | Get the target node of a reference
+| async **linkTarget** | Get the target node of a link. See `target`
+| async **joinNodes** | Get the schema nodes corresponding to link. The function returns nodes for both the source and the destination of the link. See `joins`.
+| async **reverseLink** | Returns the node corresponding to the reverse link of a link. See `revLink` to get the reverse link name rather than the actual node
+| async **computeString** | Returns the compute string of a node, following references if necessary
+| async **enumeration** | For nodes whose value is an enumeration, return the `XtkEnumeration` object corresponding to the enumeration definition. See `enum` property to get the enumeration name instead of the object
+| **firstInternalKeyDef** | 
+| **firstExternalKeyDef** |
+| **firstKeyDef** |
+
 
 
 ### XtkSchemaKey
 
 | Attribute/Method | Description |
 |---|---|
-| schema | The schema to which this key belongs
-| name |  The name of the key (internal name)
-| label | The label (i.e. human readable, localised) name of the key
-| description | A long, human readable, description of the key
-| isInternal |
-| allowEmptyPart |
-| fields | A map of key fields making up the key. Each value is a reference to a `XtkSchemaNode` 
+| **schema** | The schema to which this key belongs
+| **name** |  The name of the key (internal name)
+| **label** | The label (i.e. human readable, localised) name of the key
+| **description** | A long, human readable, description of the key
+| **isInternal** | Indicates if the key is an internal key (as opposed to an external key)
+| **allowEmptyPart** |
+| **fields** | A ArrayMap of key fields making up the key. Each value is a reference to a `XtkSchemaNode` 
 
 ### XtkEnumeration
 
 | Attribute/Method | Description |
 |---|---|
-| name |  The name of the key (internal name)
-| label | The label (i.e. human readable, localised) name of the key
-| description | A long, human readable, description of the key
-| baseType | 
-| default |
-| hasImage |
-| values | A map of enumeration values, by name of value. Value is of type `XtkEnumerationValue`
+| **name** |  The name of the enumeration, fully qualified, i.e. prefixed with the schema id
+| **label** | The label (i.e. human readable, localised) name of the key
+| **description** | A long, human readable, description of the key
+| **baseType** | The base type of the enumeration, usually "string" or "byte"
+| **default** | The default value of the enumeration, casted to the enumeration type
+| **hasImage** | If the enumeration has an image
+| **values** | A ArrayMap of enumeration values, of type `XtkEnumerationValue`
 
 ### XtkEnumerationValue
 
 | Attribute/Method | Description |
 |---|---|
-| name |  The name of the key (internal name)
-| label | The label (i.e. human readable, localised) name of the key
-| description | A long, human readable, description of the key
-| image |
-| enabledIf |
-| applicableIf |
-| value | The value of the enumeration (casted to the proper Javascript type)
+| **name** |  The name of the key (internal name)
+| **label** | The label (i.e. human readable, localised) name of the key
+| **description** | A long, human readable, description of the key
+| **image** |
+| **enabledIf** |
+| **applicableIf** |
+| **value** | The value of the enumeration (casted to the proper Javascript type)
 
 # Advanced Topics
 
@@ -1454,6 +1671,28 @@ If you need to access entity attributes (or child elements) in a generic way, yo
 * `getChildElements` to get the child elements. The result can be iterated on with a `for...of...` loop
 * `getElement` to get a child element whose attributes and child elements can also be accessed by the EntityAccessor API
 
+## Invoking SOAP calls dynamically
+Soap calls can be invoked dynamically as follows
+
+```js
+  const namespace = client.NLWS["xtkSession"];
+  const method = namespace["getOption"];
+  const result = await method.call(namespace, parameters);
+```
+
+where parameters is the list of parameters to the SOAP call.
+Parameters can be a function which can compute and return the list of parameters as the function is being called:
+
+```js
+  const result = await method.call(namespace, (method, callContext) => {
+    return parameters;
+  });
+```
+The `method` parameter is the XML definition of the SOAP method call. The `callContext` is an object which contains the following attributes:
+* `schemaId` is the id of the schema containing the SOAP method
+* `namespace` is the call namespace
+* `object` is only used for non-static call and contains the "this" of the call.
+
 
 
 # Build & Run

package/compile.js

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

package/package-lock.json

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

package/package.json

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