Scripting Context

Scripts allow you to set the value of a new attribute, adjust the value of an existing attribute, or delete an attribute by invoking a scripting language such as Javascript. Whenever a script is evaluated, a "scripting context" is established. The context is what provides the script with access to its data and functions.

self

The scripting context is an object. When the self keyword is used in a script, it refers to this context object.

Context Properties

The scripting context has these properties:

• $data -- Refers to the data object against which the script is being evaluated
• $globals -- Refers to the Global Attributes
• $actor -- Refers to the properties of the Integration or Connector

$data

The $data property is a reference to the data object against which the script is being evaluated. For example, if the following script is used in a mapping rule of the Student topic, self.$data refers to a Student object:

self.$data.local_id

The result of this script is the value of the Student's local_id attribute.

Note you can also access the $sys property of an object to reference the object identifier, object type and subtype, and timestamps:

self.$data.$sys.person_type

$globals

The $globals property is a reference to the Global Attributes. For example, if you've defined a Global Attribute named default_country, the following script uses that value if no country attribute is defined on the data object:

ifBlank("$(country)",$globals.default_country)

$actor

The $actor property is a reference to the Integration or Connector, from which select metadata about tactor, cloud, and account can be obtained. This property is not yet supported.

Directory Integrations

Directory Integrations support scripting not only in mapping rules but also in Blueprint Templates. Its context object has three additional properties:

• $parent -- A reference to the context of the parent Template
• $params -- Parameters passed to the Template
• $node -- The OrgUnit, Group, or User produced by the Template

$parent

The $parent property is a reference to the context object of the parent Template.

$params

The $params property is used to pass parameters to a Template.

$node

The $node property is a reference to the OrgUnit, Group, or User that is produced by the Template being evaluated.

Order of Evaluation

It's good practice to explicitly reference context properties by name. Doing so makes your scripts unambiguous. In the following example, it is clear that the first script is referencing a local_id attribute of the data object, and the second is referencing a Global Attribute named local_id:

self.$data.local_id

self.$globals.local_id

The same applies to functions:

self.ifBlank(self.$data.country,self.$globals.default_country)

Admittedly, referencing self and self.$data in this way is cumbersome and less readable, especially considering that the intent of most scripts is to reference an attribute of self.$data. It would be cleaner to write the above scripts as follows:

local_id

$globals.local_id

ifBlank(country,$globals.default_country)

To support this, scripting follows a specific order of evaluation when resolving an unqualified token:

• Function name
• self.$data attribute
• self.$globals attribute

In other words, when an unqualified token is encountered scripting assumes you are referencing the name of a function. If no function exists with that name, it next looks for a property of the context object with that name. If no property is found, it next looks for an attribute of self.$data with that name. If no attribute is found, it next looks for an attribute of self.$globals with that name.

Reserved Names

The order of evaluation rules require that attributes not be named the same as properties of the Context object. Data Sync considers some keywords like self and this to be reserved, as well as name that begins with a dollar sign. Consequently, you cannot use any of the following when creating attributes in mapping rules: self, this, $sys, $data, $globals, $parent, $params, $account, $actor.

See Attributes for details.

Expressions

Interopolation

Interpolation is the process of expanding "placeholders" in a string with values referenced by those placeholders. Interopolation is performed on all types of mapping rules -- including XPath and JSONPath -- before the rule is evaluated.

$(name)

Use the $(name) notation to reference an attribute. A typical use of interpolation is:

$(name.first) $(name.last)

The equivalent script is less readable:

name.first + " " + name.last

Both of these produce the same result:

Cathy Martinez

Interpolation follows the same order of evaluation rules described in Scripting Context above. Thus, each of the following are valid and equivalent means of accessing the local_id attribute of the data object:

$(local_id)
$($data.local_id)
$(self.$data.local_id)

$(table:name)

Use the $(table:name) notation to look up a value in a Lookup Table. A typical use of this style of interpolation is found in the XPath mapping rules of the SIF 2 Connector's Factory Defaults package:

AddressList/Address[@Type='$(SIF Types:student.address)']/PostalCode

This example looks up the value of the "student.address" key in the Lookup Table named "SIF Types" and returns the value. The resulting string might be:

AddressList/Address[@Type='06']/PostalCode

Empty Values

Interpolation always yields a value. If the referenced attribute does not exist, it results in an empty string.

Scripting Errors

Null Values

A common scripting error is attempting to access a property of a null or undefined value. Consider the following:

name.middle.length < 5 ? "short" : "long"

This script returns the value "short" if the middle name is less than 5 characters, and the value "long" otherwise. It's not safe because if the name.middle attribute does not exist, attempting to access its length property will result in a scripting error.

To make this script safe, use the str function to guarantee that the attribute value or an empty string is returned:

str(name.middle).length < 5 ? "short" : "long"

In general it's a good idea to always use Accessor Functions like str, date, and bool to access attribute values.

Best Practices

Refer to Scripting Best Practices for tips and recommendations.