9.1 About the ECMA Expression Builder

Designer incorporates an ECMAScript interpreter and expression editor, which allows you create script expressions that refer to and modify workflow data. For example, you can use scripting to:

  • Create new data items needed in a workflow under the flowdata element.

  • Perform basic string, date, math, relational, concatenation, and logical operations on data.

  • Call standard or custom Java classes for more sophisticated data operations.

  • Use expressions for runtime control to:

    • Modify or override form field labels.

    • Initialize form field data.

    • Customize email addresses and content.

    • Set entitlement grant/revoke rights and parameters.

    • Evaluate any past activity data to conditionally follow a workflow path by using the Condition activity.

    • Write different log messages that are conditionally triggered by using a single Log activity.

This section describes some of the techniques and capabilities applicable to the use of scripting.

NOTE:To define expressions for a workflow, you need to understand how workflow activities are configured. In addition, you need to understand the various types of data that are available within a workflow. For details on configuring workflow activities, see Section 7.0, Workflow Activity Reference. For descriptions of the system variables available in a workflow, see Understanding Workflow Data.

9.1.1 About ECMAScript

ECMAScript is an object-oriented scripting language for manipulating objects in a host environment (in this case, Designer). ECMAScript (ECMA-262 and ISO/IEC 16262) is the standards-based scripting language underpinning both JavaScript (Netscape) and JScript (Microsoft). It is designed to complement and extend existing functionality in a host environment such as Designer’s graphical user interface. As a host environment, Designer provides ECMAScript access to various objects for processing. ECMAScript in turn provides a Java-like language that can operate on those objects.

The extensibility of ECMAScript, and its powerful string-handling tools (including regular expressions), make it an ideal language to extend the functionality of Designer.

NOTE:You can find detailed information about ECMAScript at the European Computer Manufacturers Association (ECMA) Web site.

9.1.2 ECMAScript Capabilities

In addition to enabling you to incorporate finely tuned custom logic into your workflow, scripting gives you a great deal of flexibility in manipulating data because of the various DOM-related and XPath-related objects and methods available in the ECMAScript extensions incorporated into the Expression Builder.

The usefulness of ECMAScript is especially apparent when dealing with in-memory DOMs. The ECMA Expression Builder constructs XML documents as in-memory objects according to the W3C DOM Level 2 specification. The DOM-2 specification, in turn, defines an ECMAScript binding (see the W3C Recommendation ECMAScript Language Binding, with numerous methods and properties that provide ready access to DOM-tree contents. The flowdata DOM is recognized by the ECMA Expression Builder, and any of the W3C-defined ECMAScript extensions that apply to DOMs can be used.

ECMAScript also provides bridges to other expression languages such as XPath. This allows you to use XPath syntax on a DOM to address various elements within its document structure.

9.1.3 Using the ECMA Expression Builder

Designer provides access to ECMAScript in various places in the User Application design tools. The most common form of access is through the Expression Builder, which can be displayed whenever you see this button:

The button is found in Designer displays, such as the Properties for a Condition activity or the Data Item Mapping view for an Entitlement Provisioning activity. Click the button to display the ECMA Expression Builder.

The ECMA Expression Builder provides pick lists of available objects, methods, and properties in the top panes (all of which are resizable), with rollover tooltips to help you build ECMAScript statements. Double-clicking any item in any pick list causes a corresponding ECMAScript statement to appear in the edit pane in the lower portion of the window. In the figure, the process pick list has been selected in the ECMAScript Objects pane, and the name variable has been double-clicked. The ECMAScript expression that can access the contents of this workflow variable is inserted automatically in the edit pane.

Checking Syntax

The ECMA Expression Builder includes a Check Syntax button. Clicking the button causes the ECMAScript interpreter to check the syntax of the expression. If there are problems involving ECMAScript syntax, an error message is displayed. You can then edit the expression and validate again as needed. Validation is optional.

NOTE:The syntax checking process does not execute your expression. It just checks syntax. Because ECMAScript is an interpreted language, syntax checking doesn’t check any runtime-dependent expressions, other than to see if they conform to valid ECMAScript syntax.

Selecting a DN

The ECMA Expression Builder also includes an Identity Vault button that is displayed when you are working with activities that might require selecting a DN from the Identity Vault (for example, Start, Approval, and Entitlement activities).

Figure 9-1 Identity Vault Button

The Identity Vault button displays a dialog box that you use to navigate the Identity Vault to select a DN. The Identity Vault button is dimmed (to indicate that it is unavailable) if you are not connected to the Identity Vault.

ECMAScript Objects

This pane displays the names of objects that are relevant in the current context. For example, if you are working in the provisioning request definition editor, you see system variables for the current workflow process, system variables for the current activity, and flowdata variables created in the current workflow. Double-click the name of a variable to insert that variable into your script. For descriptions of the system variables available in a workflow, see Understanding Workflow Data.

The ECMA Expression Builder provides two methods for reading flowdata variables.

Table 9-1 Methods for Reading Flowdata Variables

Method

Description

flowdata.get(variable-name)

Returns a string as the node value for a variable (representing an XPath expression) in the workflow document.

flowdata.getObject(variable-name)

Returns an object as a node value for a variable (representing an XPath expression) in the workflow document. Use this method to retrieve the values of multivalued controls.

Vault Expressions

This pane allows you to insert Entity definitions (see Working with Entities and Attributes) that are defined in the Identity Vault into your scripts. Both system and user-defined entities are available. The format of an expression to retrieve data from the Identity Vault is

IDVault.get(dn, object-type, attribute)

For example if you want the recipient's manager for a data item, you would open the User node in the Vault Expressions Pane and double-click the Manager item, which inserts IDVault.get({ enter dn expression here }, 'user', 'manager'). This expression evaluates to the string for the manager’s DN (LDAP distinguished name).

Using Special Characters

You can use special characters in literal strings in the ECMA Expression Builder by using escape sequences. Escape sequences begin with a backslash character ( \ ). The following table contains some commonly used escape sequences:

Table 9-2 Escape Sequences

Escape Sequence

Character

\b

Backspace

\f

Form feed

\n

New line

\r

Carriage return

\t

Horizontal tab

\”

Double quote

\\

Backslash (\)

\’

Apostrophe

You also can specify any Unicode character by using \u followed immediately by four hexadecimal digits. Here are some examples:

Table 9-3 Escape Sequence Examples for Unicode Characters

Escape Sequence

Character

\u00A3

Pound symbol (£)

\u20AC

Euro symbol (€)

9.1.4 About Java Integration

Java is integrated into the workflow process through the ECMA Expression Builder, which provides a bridge to external Java objects. To access a Java class through the ECMA Expression Builder, the class must be in the classpath of the workflow engine. To accomplish this, you must add the Java class to the WEB-INF\lib directory in the User Application WAR file (IDM.war).

NOTE:Unlike ECMAScript that is available in other parts of the provisioning request definition editor, form action scripts are executed on the browser, not the server. All directory access from within a form action script is handled by AJAX calls from the browser to the server. See Form Action Script Methods.

Adding the Java Class to the User Application WAR

  1. Use a WAR file utility to open the IDM.war file. The IDM.war file is located in the application server \server\IDM\ directory.

  2. Copy the Java class into the WEB-INF\lib directory.

Accessing Java from ECMAScript

To access a Java class, create a function inline in the ECMA Expression Builder. Instantiate the function, then within the function, use ECMAScript syntax to call your Java methods. The following example creates a vector:

function list() { v=new java.util.Vector(); v.add('{Enter Item 1}'); v.add('{Enter Item 2}'); return v; };  list();

To access a custom Java class, you must preface the class name with “Packages”. For example:

v = new Packages.com.novell.myClass("value");

The ECMA Expression Builder is built on Mozilla Rhino. Rhino is an open source implementation of JavaScript written entirely in Java. For more information about accessing Java from ECMAScript, see Scripting Java.

9.1.5 About XPath Integration

XPath in Workflows

A provisioning request definition workflow supports a special object called flowdata (see Understanding Workflow Data). The flowdata object is a DOM (an XML document constructed as an object in memory). You can use XPath syntax to navigate the structure of the flowdata DOM, and add, modify, or delete elements and contents.

To add an object to flowdata:

Syntax

Examples

flowdata.parent/child[1]
flowdata.reason

To get an object from flowdata:

Syntax

Examples

flowdata.getObject('parent/child[1]')
flowdata.get('reason')

For information about the flowdata.get() and flowdata.getObject() methods, see Table 9-1.

XPath in Integration Activities

When you are working with an Integration activity, the ECMAScript interpreter recognizes a custom method called XPath(). This method allows expressions such as:

Input.XPath("GetBNQuoteSoapIn/GetBNQuote/sISBN")

When you use the ECMA Expression Builder, this type of expression is built for you automatically when you select nodes in ECMA Expression Builder pick lists.

The Integration activity uses the XPath addressing syntax adopted by W3C. The XPath syntax is similar to URL address syntax but includes many subtle and powerful features for addressing and manipulating XML. Some of the more common syntax rules are listed in the following table.

Table 9-4 XPath Syntax

XPath Syntax

Description

/

The single forward slash represents an absolute path to an element. For example, /ABC selects the root element ABC.

//

Double slashes represent all elements in a path. //ABC selects all occurrences of ABC. For example, //ABC//DEF selects all DEF elements that are children of ABC.

*

The asterisk selects all elements located by the preceding path. For example, *ABC/DEF selects all elements enclosed by elements ABC/DEF. //* selects all elements.

[ ]

Square brackets specify a particular element. For example /ABC[3] selects the third element in ABC. This can also be used as a filter (similar to a Where clause in SQL). //ABC["Table"] selects all elements that have the content “Table.”

@

The At sign selects elements with a specified attribute. For example, /ABC@name selects all elements in ABC that have an attribute called name.

|

The vertical bar allows you to specify multiple paths. For example, //ACB|//DEF selects all elements in ACB and in DEF.

$

The dollar sign allows you to reference other documents in addition to the current one: INVOICEBATCH/INVOICE[SELLER/NAME= $PROJECT/USERCONFIG/COMPANYNAME]

function()

XPath has numerous functions that you can add to your XPath addresses. For example, //*[count(*)=2] selects all elements that have two children.

math operator()

XPath has numerous math operators that you can add to your XPath addresses. For example, /ABC|position() mod 2 = 0] selects all even elements in ABC.

You can find the complete list of operators in the W3 Recommendation XML Path Language (XPath).

9.1.6 About Global Configuration Values Integration

Global configuration values (GCVs) are settings that are similar to driver parameters. Global configuration values can be specified for a driver set, as well as for an individual driver. If a driver does not have a GCV, the driver inherits the value for that GCV from the driver set.

GCVs are integrated with the workflow process through the ECMA Expression Builder, which provides a bridge to the GCVs from the driver and the GCV resource objects. To access a GCV through the ECMA Expression Builder, go to the variables pane and select any GCV from the GCV list. For GCV resource objects to be available on the variable pane, ensure that they are linked to the User Application driver. These GCVs are available to you in all activities on the workflow and not on the forms.

NOTE:

  • When you create a GCV of the type password-ref (Named Password), ensure that you create the GCV on the specific driver itself and not on the driver set.

  • If you include a password-ref GCV in a workflow, you must also create and include a separate Boolean GCV named allow-fetch-named-passwords and set the value of that GCV to true If you do not include the second Boolean GCV, the workflow fails with a scripting error.

9.1.7 About Global ECMAScripts Integration

ECMAScripts that are globally available on the User Application drivers or within the Identity Vault libraries can be accessed through the Expression Builder. Ensure that ECMA Scripts are imported into the provisioning request definition from the Overview page. For more information about creating provisioning request definitions, see Section 4.0, Configuring Provisioning Request Definitions.

The global ECMAScripts are available throughout all your activities and on the forms. For making them available, you should include them as necessary on workflow activities, start activity, and forms.

9.1.8 Performance Considerations

ECMAScript is an interpreted language, which means that every line of script in an expression must be parsed and translated to the Java equivalent before it can be executed. This adds considerable overhead to the code and results in overall slower execution of scripts than pure Java. Before using ECMAScript, you should think about the possible performance consequences.

The following guidelines help you to achieve optimal performance in your components and services:

  • Consider whether a task can be accomplished by using a custom Java class (that you can call from ECMAScript).

  • When you need the fine control offered by scripting, use ECMAScript.

Bear in mind that the key to good performance is always a good implementation (for example, choosing the correct algorithm and attention to reuse of variables). Good code written in a slow language often outperforms bad code written in a fast language. Writing something in Java does not guarantee that it will be faster than the equivalent logic written in ECMAScript because Java has its own overhead constraints, such as constructor call-chains (when you call a constructor for a Java object that inherits from other objects, the constructors for all ancestral objects are also called).

ECMAScript’s core objects (String, Array, Date, etc.) have many built-in convenience methods for data manipulation, formatting, parsing, sorting, and conversion of strings and arrays. These methods are implemented in highly optimized Java code inside the interpreter. It is to your advantage to use these methods whenever possible, rather than creating customized data-parsing or formatting functions. For example, suppose you want to break a long string into substrings, based on the occurrence of a delimiter. You could create a loop that uses the String methods indexOf() and substring() to parse out the substrings and assign them to slots in an array. But this would be a very inefficient technique when you could simply do the following:

var myArrayOfSubstrings = bigString.split( delimiter );

The ECMAScript String method split() breaks a string into an array of substrings based on whatever delimiter value you supply. It executes in native Java and requires the interpreter to interpret only one line of script. Trying to do the same thing with a loop that iteratively calls indexOf() and substring() would involve a great deal of needless interpreter and function-call overhead, with the accompanying performance hit.

Skillful use of built-in ECMAScript methods pays worthwhile performance dividends. If you use scripts extensively, take time to learn about the fine points of the ECMAScript language because this can help you eliminate performance bottlenecks.