Chapter 9   Using Scripts


This chapter describes how to use the scripts available in Process Builder. It also briefly discusses creating your own scripts.

This chapter includes these sections:

• Overview of Scripts

• Predefined Scripts

• Creating Scripts

• Using Client-side Scripts

Overview of Scripts

---

By using scripts, you can customize and configure your application's activities, automated activities, entry points, exit points, decision points, and transitions. For example, scripts let you assign users to activities and set expiration dates of activities.

Kinds of Scripts

Some scripts are provided with Process Builder, but you can also create your own. All scripts for an application are stored in the Script Dictionary in the application tree view. Table 9-1 describes the available scripts. Each type has its own purpose and its own return value.

Note. Each type of script has its own folder within the Script Dictionary. You can drag scripts from one folder to another, but you must update the script so that it returns the data required by the new type before the script will work.

Table 9-1 Available JavaScript scripts

Kind of Script	Purpose	Return Value
Assignment	Assigns a user or users to perform a work item.	Returns an array containing the user ids and/or group names of the users and/or groups to whom this work item is assigned.
Automation	Performs an automated activity. It is executed when the process reaches the automated activity.	Returns true if the activity is successful, otherwise returns false.
Verification	Executes when a work item is completed.	Returns true if the activity is successfully verified, otherwise returns false.
Completion	Executes when a work item is completed. This script runs after the verification script.	Returns true if the activity is successful, otherwise returns false.
Expiration Setter	Sets the expiration date of a work item.	Returns a Date object.
Expiration Handler	Runs when a task has not been completed before its expiration date is reached.	Returns true if the expiration is successfully handled, otherwise false.
Email Address in Notification	Specifies an email address to which a notification will be sent, either in the To: line or Cc: line.	Returns a valid email address, or a comma-delimited list of valid email addresses. Values can be passed as a string or as a JavaScript array.
Email Subject in Notification	Specifies the subject of an email message.	Returns a string specifying the subject of the email message.
Email Body in Notification	Specifies the body content of an email message.	Returns a string specifying the body of the email message.
Decision point or automation script condition	Specifies a condition that is used to determine which path to follow in the process.	Returns true if the condition is met otherwise false
Initialization script	Specifies tasks to perform when the application first starts.	Returns true if the initialization is successful, otherwise false
Shutdown script	Specifies tasks to perform when the application shuts down.	Returns true if the shutdown is successful, otherwise false
Toolkit script	A library function. It can be called by other functions or used as the value of any script for which it returns the appropriate kind of value.	Returns whatever is appropriate.

When to Use Scripts

To edit a script, double-click it in the application tree view, or highlight it and click Inspector. The script text appears in a text edit window. You can also edit scripts using other tools by opening the files where they are stored on your local machine (usually in the builder/Applications folder).

Table 9-2 shows what kinds of scripts are available for you to use at each process step.

Table 9-2 Script Types by Process Step

Script Type	Entry Point	User Activity	Automated Activity
Assignment		Available
Automation			Available
Expiration setter		Available
Expiration handler		Available
Verification		Available	Available
Completion	Available	Available	Available

About Writing Scripts

You can define your own server-side scripts for any situation where scripts are used. The scripts must be written in JavaScript. You can write them in the script editor in Process Builder. Or you can write them in the editor of your choice, but you must later import them into Process Builder.

Scripts can use any core JavaScript language and objects, such as array or date. Scripts can also use additional objects that are provided by Process Manager. These objects include processInstance, workItem, corporateDirectory and contentStore. These scripts cannot use client-side objects such as document and window.

For more information about writing scripts, see Chapter 11 "Advanced Techniques for Scripting."

Predefined Scripts

---

Process Manager provides a set of predefined server-side scripts, all of which can be accessed from Process Builder. The scripts fall under the following categories:

• Assignment Scripts

• Completion Scripts

• Email Notification Scripts

• Initialization and Shutdown Scripts

Assignment Scripts

Table 9-3 lists the predefined assignment scripts that are available in Process Builder. The documentation below explains what they do, and what parameters you need to supply when you use them to assign a user to an activity. See Setting Activity Assignments for more information on using assignment scripts in activities. For details on creating assignment scripts, see Appendix AJavaScript API Reference.

Table 9-3 Assignment Scripts 

Script	Description
randomToGroup	This script selects a user randomly from the users that belong to the group specified by groupname. The parameter to edit is groupname, which is the name of the group that is defined in the Groups and Roles folder. It can be an application group, a corporate group, or a dynamic group. You can improve performance by making the group that is passed as a parameter able to be cached.
toCreator	This script returns a JavaScript array user ID of the user who created the process instance. toCreator is the default assignment script for a user activity. This script accepts no parameters.
toGroup	This script returns a JavaScript array of User IDs of all members of the group specified by the groupName parameter. If this parameter does not correspond to an actual group in the application's Groups and Roles folder, this script returns null.
toManagerOfCreator	This script assigns the work item to the manager of the user who created the process instance. The manager relationship is based on the manager entry of the user in the corporate user directory. For this script to return the manager of the user, the manager attribute of the user in the corporate user directory must contain the distinguished name (DN) of the manager. No parameters need to be edited in this script.
toManagerOfRole	This script assigns the work item to the manager of the person defined in a field role. The manager relationship is based on the manager entry of the user in the corporate user directory. For this script to return the manager of the user, the manager attribute of the user in the corporate user directory must contain the distinguished name (dn) of the manager. The parameter to edit is rolename, which is the name of the field role defined in Groups and Roles folder.
toManagerOf	This script assigns the work item to the manager of the user specified by its user ID. The manager relationship is based on the manager entry of the user in the corporate user directory. For this script to return the manager of the user, the manager attribute of the corporate user directory entry of the user must contain the distinguished name (dn) of the manager. The parameter to edit is userID, which is the user ID of the person whose manager you want to assign an activity to.
toUserById	This script assigns the work item to a user based on the user ID. The parameter to edit is userID, which is the user ID of the person to whom you want to assign the activity.
toUserFromField	This script assigns the work item to the user whose user ID is stored in the datafieldname field of the process instance data. The DN of the user is stored in this field. If you have a field role, using this script has the same affect as assigning the work item to the field role on the Assignment Selection dialog box using the "A group or role" radio button. The parameter to edit is datafieldname, which specifies the name field where the user ID has been stored. This field has to exist in the application data dictionary and has to contain the user ID of the user the work item should be assigned to.
toParallelApproval	This script assigns the activity to all the people specified in arrayOfUserIDs, and tracks if they approve or reject the item they are approving. You also need to use the checkParallelApproval completion script. The parameters to edit are arrayOfUserIDs and FieldName. The arrayOfUserIDs is a JavaScript array which contains the user IDs of the people who need to perform the approval. The FieldName is the field that keeps track of who has performed the approval and who still needs to do so. The field is a computed field of length 2000 that you have to add to the data dictionary.

Completion Scripts

There is one predefined completion script, checkParallelApproval. It is used for parallel approval.

This script runs when the parallel approval activity is completed. If any user chooses the "stopper action" (that is, refuses to approve the item) the completion script performs the appropriate action. If all users complete the activity without choosing the stopper action (that is, all approve the item) this script performs the appropriate action.

The parameters are FieldName and labelOfStopperAction. The FieldName is the field that keeps track of who has performed the approval and who still needs to do so. The field is a computed field of length 2000 that you have to add to the data dictionary. The labelOfStopperAction is the name of the action that a user can take that stops the approval.

For more information on parallel approval, see Using Parallel Approval.

Verification Scripts

There are no predefined verification scripts.

Email Notification Scripts

This section describes the predefined email notification scripts:

• defaultNotificationHeader()

• defaultNotificationSubject()

• emailById(userId)

• emailOfAssignees()

• emailOfCreator()

• emailOfRole(role)

For examples of using these scripts, see the Process Manager Programmer's Guide.

defaultNotificationHeader()

Returns the default notification header for a notification message body. The header contains information about the current work item, such as the current activity name, the process instance ID, the creation date of the process instance and the expiration date (if any).

This function may be used as the notification body script by itself, or may be embedded in your own notification body script. You may also use this function from a template evaluated using evaluateTemplate(). The function may only be used successfully from a script associated with a notification; if used anywhere else, an empty string is returned.

The text returned from this function will depend upon the content-type of the notification. If the content-type is text/html, the header will be a series of HTML tags; if the content-type is text/plain, the header will be plain text.

defaultNotificationSubject()

Returns the default notification subject for the notification subject line. The subject contains information about the current process instance, such as the process instance ID the priority and the title string.

This function may be used as the notification subject script by itself, or may be embedded in your own notification subject script. The function may only be used successfully from a script associated with a notification; if used anywhere else, an empty string is returned.

emailById(userId)

Returns a string of comma-delimited email addresses for the user with the given user ID. The mail attribute for the user must contain a valid email address in the corporate user directory. If the mail attribute of the user does not have a value, this function logs an error and returns null. This function is intended for use as a notification script, but can be used anywhere that a string of email addresses is needed.

emailOfAssignees()

Returns a string of comma-delimited email addresses for all the assignees of the work item. The mail attribute for each assignee must contain a valid email address in the corporate user directory. If the mail attribute is empty for any assignee, no address is added to the string for that assignee. If no assignee has a value in their mail attribute, the function logs an error message and returns null. This function is intended for use as a notification script, but can be used anywhere that a string of email addresses is needed.

emailOfCreator()

Returns a string of the email address of the user who created the process instance. The user's mail attribute must contain a valid email address in the corporate user directory. If the mail attribute of the user does not have a value, this function logs an error and returns null. This function is intended for use as a notification script, but can be used anywhere that a string of email addresses is needed.

emailOfRole(role)

Returns a string of the email address of the user performing the given role. The user's mail attribute must contain a valid email address in the corporate user directory. If the mail attribute of the user does not have a value, this function logs an error and returns null. This function is intended for use as a notification script, but can be used anywhere that a string of email addresses is needed.

Initialization and Shutdown Scripts

In addition to the predefined assignment scripts, every new application you create has an initialization script and a shutdown script in the script dictionary. The initialization script is called when the application is initialized, and the shutdown script is called when the application stops.

You can use the initialization script to set variables and create objects that are needed for the duration of the application. You use the shutdown script to release any resources allocated by the initialization script, and perform any final cleanup needed.

Creating Scripts

---

In addition to using the predefined scripts described in this chapter, you can also create your own scripts.

To create a script, perform the following steps:

1. From the Insert menu, choose Script. The Create a New Script dialog box appears, as shown in Figure 9-1.

2. Name the script. The name must contain only alphanumeric characters.

3. Choose the type of script you want to create:
   • Assignment Script

   • Automation Script

   • Expiration Setter Script

   • Expiration Handler Script (also known as an Expire script or an On Expire script)

   • Verification Script

   • Completion Script

   • Toolkit Script

Figure 9-1    The Create a New Script dialog box

4. Click a radio button to choose how you want to create the script.
   • "Create from a blank window" lets you type your script into a blank window, without basing it on an existing script. If you choose this radio button, go to Step 5.

   • "Create from a template function" lets you base your script on another script of the same type which you have previously designated as a template. If you choose this radio button, choose a template from the drop-down list, and go to Step 5.

   • "Create from an imported file" lets you import an existing script from outside the application, or copy one from within the application. If you choose a script from outside the application, you can save the script with the same name. If you choose a script from the current application, you must give the script a unique name. Click Browse to navigate to the .js file you want, and then click Open. Then go to Step 5.

5. Click Create. Your new script appears in the Script Editor Window.

Note. The .js files you import must follow the conventions for .js files in Process Manager. The name of the file must be the same as the name of the script, and each file can contain only one script.

The Script Editor Window

The script editor window appears when you are creating a new script or editing an existing script. If you are creating a new script from a blank window, the script editor appears with comments in the window pertaining to the type of script you are creating.

The script editor has a text area for typing in your script, and several buttons at the top, as shown in Figure 9-2.

Figure 9-2    A portion of the script editor window

OK. Saves changes to the script and closes the window.

Revert. Rolls back any changes you've made since the last time you saved the script. The window remains open.

Close. Closes the window without saving changes.

Help. Launches a web page containing help about this script.

Goto. Lets you specify a line number to go to in the script.

Find. Lets you specify a text string to search for in the script.

Check Syntax. Checks the syntax of the script you've created, and displays an error message if there is an error.

Setting a Script as a Template

If you want to use a script as the basis of future scripts within the current application or other applications, you need to designate it as a template. To set it as a template, follow these steps:

1. In the application tree view, right click on the script name.

2. From the menu, choose "Set as template".

The script is added to the drop-down list of templates that appears when you insert a new script. You can only use a template to create the same type of script. For example, an assignment script template only appears in the drop-down list if you are creating a new assignment script.

If you choose to create a script based on a template, the new script must have a different name from the template script.

When inserting a new script, if you choose to define it from a template function, the body of the template function will be used as the body of the new script. You can then modify the new script to suit your needs.

For example, suppose you define a function called checkPageCount() that checks if the value of the pageCount field is a number. Then you set it as a template function. Next time you need a script to check that the value of a different field is a number, you could create the new script from the checkPageCount() template script, and replace references to pageCount by the desired field.

Using Client-side Scripts

---

Most of this chapter describes server-side scripts that run at various stages in the life cycle of a process instance. However, you may also need to know something about client-side scripts. This section describes information that you may find useful.

Process Builder supports the following client-side scripts:

• Embedded client-side scripts. These are attached by using Process Builder's Insert menu, then the HTML element submenu, and then choosing the Client JavaScript menu command.

• Event handlers for form elements. Event handlers include scripts such as onValueChange and onClick.

Client-side scripts run in the web page and can access other objects, such as form elements, in the current page. Client-side scripts can use the standard JavaScript language and client-side objects such as form, window and document that are available to all client-side JavaScript scripts.

Every web page displaying a work item contains a single form, which client-side scripts can access using forms[0]. For example, the following statement sets the variable budget to the value currently showing in the form element named budget:

var budget = document.forms[0].budget.value;

Every data field represented on a form has an associated form element of the same name. For example, if the AuthorName field is represented on the form, then the form contains a form element whose name is AuthorName. In some cases, this form element is hidden, but in all cases, such a form element exists.

Thus, client-side scripts can access the value of any data field as it is currently displayed in the form. This is done by accessing the value of a form element that has the same name as the data field. Client-side scripts cannot get the value of a data field that is not represented in the form.

For example, the following embedded client-side script displays a message indicating how much money is left on the budget:

var budget = document.forms[0].budget.value; var amountSpent = document.forms[0].amountSpent.value; var amountLeft = budget - amountSpent; document.write("<B><FONT COLOR='#CC55BB'> $" + amountLeft + " </FONT></B> ");

Figure 9-3 shows the definition of this embedded script in Process Builder, and Figure 9-4 shows the results of this embedded script in Process Express.

Figure 9-3    Defining an embedded client-side script in Process Builder

Figure 9-4    Results of an embedded script in Process Express

Note that an embedded script can access only those form elements that precede it physically in the page, because scripts are executed as the page is laid out. By contrast, event handlers can access other form elements no matter where they are in the page.