The Application Object

The application object can be obtained from a client, and will mimmic the Campaign Application object

Attribute/Method	Description
buildNumber	The server build number
version	In SDK version 1.1.4 and above, returns the server version formatted as major.minor.servicePack (ex: 8.2.10)
instanceName	The name of the Campaign instance
operator	Information about the current operator (i.e. logged user), of class CurrentLogin
packages	List of installed packages, as an array of strings
async getSchema(schemaId)	a schema by id (see the Schemas section below)
async getEnumeration(enumerationName, schemaOrSchemaId)	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
instanceLocale	The locale of the instance
rights	An array of strings describing the rights of the operators

Schema API (aka XtkNodeDef)

The Schema API is the Campaign API which allows to access schemas and the corresponding node hierarchy in a programmatic way. It's simpler to use this API than to manipulate XML or JSON. The name XtkNodeDef comes from "Xtk Node Definition", where an XtkNode is a generic node in a schema definition.

The Schema API closely mimmics the Campaign server side API with the following differences:

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:

const application = client.application;
const schema = await application.getSchema("nms:recipient");

This return a schema object of class XtkSchema

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.

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

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

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

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:

const schema = await client.application.getSchema("nms:recipient");
// comma separated list of enumerations
const enumerations = schema.enumerations.map(e => e.name).join(',');

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.

const schema = await client.application.getSchema("nms:recipient");
// deprecated, discouraged
for (const key in schema.enumerations) {
    ...
}

Traversing schemas

The schema API is useful to quickly traverse in the schema hierarchy. Here are a few examples

Get the label of the email attribute of the nms:recipient schema

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.

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:

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

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

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/Method	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.
labelLocalizationId	The translation id of the label 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.
labelSingularTranslationId	The translation id of the label of the node of the singular label.
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. 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/Method	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.
dbEnum	Returns a string of characters which provides the db enum of the current node.
description	A long, human readable, description of the node
descriptionLocalizationId	The translation id of the 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	Returns a boolean which indicates whether the current node is an automatic UUID
isAutoStg	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. There are some inconsistencies in ACC schemas, and sometimes attributes may be defined as both sql and xml (for example: nms:delivery/properties/seedProcessed). Such nodes with have both isSql=true and isMappedAsXml=true
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.
labelLocalizationId	The translation id of the label 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?
visibleIf	The visibility expression of the node (if any) since version 1.1.9 of the SDK
belongsTo	For attribute and elements, indicates the schema id in which they were defined. Since version 1.1.10 of the SDK
default	Default value if any. Can be an array for collections. Since version 1.1.24 of the SDK
translatedDefault	Default value if any. Since version 1.1.24 of the SDK
ordered	If children are ordered
doesNotSupportDiff	If returning the whole node when comparing difference

Methods of a schema node

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	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 enumeration, fully qualified, i.e. prefixed with the schema id
label	The label (i.e. human readable, localised) name of the key
labelLocalizationId	The translation id of the label of the key.
description	A long, human readable, description of the key
descriptionLocalizationId	The translation id of the 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
labelLocalizationId	The translation id of the label of the key.
description	A long, human readable, description of the key
descriptionLocalizationId	The translation id of the description of the key.
image
enabledIf
applicableIf
value	The value of the enumeration (casted to the proper Javascript type)

Adobe Campaign JavaScript SDK