Appendix A   JavaScript API Reference


This appendix is an API reference of the objects and methods you can use when writing JavaScript scripts for Process Manager.

The Process Manager Object Model includes the following objects:

• ProcessInstance contains methods for accessing information about the current process.

• WorkItem contains methods for accessing information about the current work item.

• ContentStore contains methods for accessing the content store.

• CorporateDirectory contains methods for accessing data about users in the Directory Server.

• User exposes the user attributes that make up an LDAP user entry as publically accessible properties.

The following global functions are also available for use in scripts:

• Logging and Error Handling Global Functions

• Assignment, Completion, and Email Scripts

• Miscellaneous Global Functions

All functions and methods are listed here:

• Alphabetical Summary of JavaScript Methods and Functions

ProcessInstance

---

A script can use the global function getProcessInstance() to get the processInstance for process in which the script is running.

Example:

var pi = getProcessInstance ();

The following methods can be called on the processInstance object:

getConclusion	getExitNodeName()	setData
getCreationDate	getInstanceId ()	setEntityKey
getCreatorUser	getPriority	setPriority
getData	getRoleUser	setRoleById
getEntityKey	getTitle	setTitle
getEntryNodeName

getConclusion

Returns the name of the exit point node where the process instance is completed. Data is returned as a JavaScript string if the process instance is complete. If the process instance is still active, null is returned.

Example:

var pi = getProcessInstance();

var exitNodeName = pi.getConclusion();

if( exitNodeName != null )

   java.lang.System.out.println( "Process instance completed at: " + exitNodeName );

It is recommended that you use getExitNodeName rather than getConclusion as getConclusion may be deprecated in future releases.

getCreationDate

Returns a JavaScript date that represents the date when the process instance was first created.

Example:

var pi = getProcessInstance();

java.lang.System.out.println( "Process instance created on: " + pi.getCreationDate() );

getCreatorUser

Returns an object that contains the attributes of the creator user in the corporate directory.

Example:

var pi = getProcessInstance ();

var creator = pi.getCreatorUser ();

java.lang.System.out.println( "Process instance creator id: " + creator.getUserID() );

getData

Returns the value of the data field or undefined if the field is not defined. The returned value is in JavaScript format.

Parameters

fieldname

String of the field name whose value is being retrieved

Example

var pi = getProcessInstance ();

var cust_name = pi.getData( "customer_name" );

java.lang.System.out.println( "The value of Customer Name: " + cust_name );

getEntityKey

Returns the entity key associated with the custom field whose name is passed as an argument. This key is stored in the process instance and is set using the setEntityKey method. The entity key is the primary key for the field, uniquely identifying it from other instances of the same custom field.

Parameters

fieldName

String of the name of the custom field for which you want to fetch the entity key.

Example:

var pi = getProcessInstance();

pi.getEntityKey("mySignature");

getEntryNodeName

Returns a JavaScript string containing the name of the entry point node where the current process instance was initiated. All process instances must start from an entry node, ensuring that this method never returns null.

Example:

var pi = getProcessInstance();

java.lang.System.out.println( "Process instance entry node if " + pi.getEntryNodeName() );

getExitNodeName()

Returns a JavaScript string containing the name of the exit point node where the process instance has completed. If the process instance has not yet completed, returns null.

Example:

var pi = getProcessInstance();

var exitNodeName = pi.getExitNodeName();

if( exitNodeName != null )

   java.lang.System.out.println( "Process instance completed at: " + exitNodeName );

getInstanceId ()

Returns the ID of the process instance, such as "2345". The id is generated by the engine to be unique across all process instances of all applications defined in the same cluster.

Example:

var pi = getProcessInstance();

var pid = pi.getInstanceId();

java.lang.System.out.println( "The Process Instance ID: " + pid );

getPriority

Returns a JavaScript number representing the priority value of the current process instance. The priority value ranges from 1 (highest) to 5 (lowest). The priority value is derived from the value of a data element. If the data element's type is INT/FLOAT, the priority value is fetched from the data element's value. Otherwise, the default value 3 is returned.

Example:

var pi = getProcessInstance();

var priority = pi.getPriority();

if( priority == 1 )

   java.lang.System.out.println( "The process instance has high priority" );

else if( priority == 5 )

   java.lang.System.out.println( "The process instance has low priority" );

else

   java.lang.System.out.println( "The current priority is " + priority );

getRoleUser

Returns a JavaScript User object that contains the attributes of the user that has been assigned to the role roleName. If a user is not associated with the role roleName yet, null is returned.

Parameters

roleName

String of the name of the role whose full DN is returned.

Example:

var pi = getProcessInstance ();

var u = pi.getRoleUser( "role1" );

if(u != null )

   java.lang.System.out.println( "role user id: " + u.getUserId() );

getTitle

Returns the current title string associated with the process instance. Calling this method is similar to calling getData() on the title data field and casting the value to a string. If the title data field has a type other than TEXT/LONG TEXT, returns a textual representation of the data element's value.

Example:

var pi = getProcessInstance();

java.lang.System.out.println( "The current title is: " + pi.getTitle() );

setData

Associates the object fieldValue with the data element fieldName. The object passed by fieldValue can be any valid JavaScript object (such as String, Date, Array). The object can be a Java object if the data element is a custom field.

Parameters

fieldName	String of the name of the data element whose value is modified.
fieldValue	Object which is the value associated with the data element fieldName.

Since each data element is configured with a particular dta type which is set at design time in Process Builder, be aware of the following data conversion guidelines:

Data element type	fieldValue type	fieldValue converted to...
TEXT/LONGTEXT	any type	String
INT	String	int
INT	Integer	int
FLOAT	String	float
FLOAT	Integer	float
DATE/DATETIME	String	Date
DATE/DATETIME	Date	Date

Example:

var pi = getProcessInstance ();

pi.setData( "customer_name", "Joe" );

//Set value for custom field

//

var custAcct = new Packages.com.acme.Account();

pi.setData( "customer_acct", custAcct );

setEntityKey

Sets the entity key of a custom field. The entity key is the primary key for the field, uniquely identifying it from other instances of the same custom field. The entity key is always available from the process instance, and is stored with the rest of the application data.

Parameters

fieldName	String of the name of the custom field you want to modify.
value	Object which is the value of the custom field's entity key.

Example:

var pi = getProcessInstance() ;

pi.setData ("mySignature" , pi.getData("signature") ) ;

pi.setEntityKey("mySignature" , "bob") ;

setPriority

Changes the current priority value for the process instance to the integer value value. A valid priority value can range from 1 (highest) to 5 (lowest). If a value smaller than 1 is passed, the priority is set to 1. If a value larger than 5 is passed, the priority is set to 5. If a non-integral value is passed through vluae, an attempt is made to convert that value to an integer. If the value cannot be converted to an integer, the priority is left unchanged.

Parameters

value

Integer value to be set as the current priority for the process instance.

Example:

var pi = getProcessInstance();

pi.setPriority( 3.141592 ); //priority := 3

pi.setPriority( -1 ); //priority := 1

pi.setPriority( "99" ); //priority := 5

setRoleById

Changes the user associated with the role roleName by specifying the new user's ID via userId. Returns true if userId corresponds to an actual user in the corporate directory and the user associated with roleName is changed. Returns false if userId does not correspond to an actual user entry and roleName is left unchanged.

Parameters

roleName	String of the name of the role to alter.
userDN	String of the DN of the user to associate with roleName.

Example:

var pi = getProcessInstance ();

if( pi.setRoleById( "joe" ) )

   java.lang.System.out.println( "role has been changed" );

else

   java.lang.System.out.println( "role has not been changed" );

setTitle

Changes the current title for the process instance to the value contained in title.

title can be any valid JavaScript object, but the resulting title is the string representation of the passed object. Calling setTitle(title) does not change the value of the title data element; the binding is uni-directoional from the data element to the process instance title.

Parameters

title

Object which is the value to be set as the current title for the process instance.

Example:

var pi = getProcessInstance();

pi.setTitle( "a new title" ); //title := "a new title"

pi.setTitle( new Date() ); //title := "Tue Oct 19 13:04:50 CDT 1999"

pi.setTitle( 3.141592 ); //title := "3.141592"

WorkItem

---

A script can use the global function getWorkItem() to get the work item in which the script is running.

Example:

var wi = getWorkItem();

The following methods can be called on the workItem object:

addUserAssignee	getCurrentActivityCN	moveTo
addRoleAssignee	getExpirationDate	removeAssignees
expire	hasExpired	resume
extend	isStateActive	setExpirationDate
assignees	isStateRunning	suspend
getCreationDate	isStateSuspended

addUserAssignee

addUserAssignee(userID)

Adds the given user as an assignee for the work item.

Parameters

userID

User ID of the user to be added as an assignee.

The following script adds the user whose uid is jocelynb as an assignee to the work item.

Example:

var wi = getWorkItem(); wi.addUserAssignee("jbecker");

addRoleAssignee

addAssigneeRole(roleName)

Adds the given role as an assignee for the work item.

Parameters

roleName

Name of the role.

expire

This function adds a flag indicating that the work item has expired. The function does not render the work item inactive.

Example:

var wi = getWorkItem(); wi.expire();

extend

Extends the duration of the work item by pushing out its expiration date. If the work item was expired, this function removes the expired flag.

Parameters

newDate

Date object for the new expiration date for the work item.

Example:

var wi = getWorkItem();

var now = new Date();

// Set extension date to 1 hour in the future

var newDate = new Date( now.getTime() + (1 * 60 * 60 * 1000) );

wi.extend( newDate );

assignees

For work items that are running, this method returns a JavaScript array of the distinguished names of the assignees. Since automated activities are performed by Process Engine and do not require an assignee, use this method only from a user activity.

Example:

var wi = getWorkItem();

var cd = getCorporateDirectory();

//Set the assignees for the workitem

var joe = cd.getUserById( "joe" );

var bob = cd.getUserByid( "bob" );

var assignees = new Array( joe.getDN(), bob.getDN() );

wi.assignTo( assignees );

var nAssignees = wi.getAssigneesDN();

for( var i = 0; i < nAssignees.length; i++)

   java.lang.System.out.println( "Assignee " + i + " is " + nAssignees[ i ] );

getCreationDate

Returns a JavaScript date that represents the creation date of the work item.

Example:

var wi = getWorkItem();

java.lang.System.out.println( "Work item created on: " + wi.getCreationDate() );

getCurrentActivityCN

Returns a JavaScript string containing the name of the activity where the work item is positioned. When called from an exception activity, returns the name of that exception activity rather than the name of the activity where the exception condition occurred.

Example:

var wi = getWorkItem();

java.lang.System.out.println( "Work item positioned at node " + wi.getCurrentActivityCN() );

getExpirationDate

Returns a JavaScript Date object that represents the expiration date of the work item.

Example:

var wi = getWorkItem();

java.lang.System.out.println( "Work item set to expire at " + wi.getExpirationDate() );

hasExpired

Returns true if the work item has expired or false if it has not expired. If the work item has already expired, but has been extended via the extend() method, hasExpired() returns false if called again.

Example:

var wi = getWorkItem();

if( wi.hasExpired() == false )

   wi.expire(); //expire immediately

isStateActive

Returns true if the work item is active or false if the work item is inactive. A work item is considered active if there is only one assignee currently assigned to it. If a work item has been assigned to a group, the work item is not active, but running. Once one member of the group elects to work on the item, it is considered active.

Example:

var wi = getWorkItem();

if( wi.isStateActive() 0

   java.lang.System.out.println( "Work item is active" );

else

{

   var nAssignees = wi.getAssigneesDN();

   if( nAssignees.length > 1 )

      java.lang.System.out.println( "Work item is running"

);

      else

      ; //work item could be suspended

}

isStateRunning

Returns true if the work item is running or false if it is not running. A work item is running if more than one user is assigned to it. Once a user starts the work item, the work item changes state from running to active.

Example:

var wi = getWorkItem();

if( wi.isStateRunning() )

{

   var nAssignees = wi.getAssigneesDN*();

   if( nAssignees.length > 1 )

      java.lang.System.out.println( "Work item is assigned to a group" );

   else

      ;

}

isStateSuspended

Returns true if the work item is suspended or false if it is not suspended. You can suspend a work item through Process Administrator or by calling suspend().

Example:

var wi = getWorkItem();

if( wi.isStateSuspended() )

   wi.resume(); //resume the work item immediately

moveTo

Move the current work item to the activity specified in activityName. Only activities associated with a virtual transition can use this method. moveTo() can only be called from expriation handler scripts and completion scripts.

Note that moveTo() doesn't actually involve "moving." Rather, the current work item is destroyed and a new work item is created at the new activity.

Parameters

activityName

String of the name of the activity to which to move the work item.

Example:

var wi = getWorkItem(); //inside the expiration handler script

var activityName = "expired item";

if( wi.moveTo( activityName ) )

   java.lang.System.out.println( "Successfully moved to activity " + activityName );

else

   java.lang.System.out.println( "Failed to move to activity " + activityName ) ;

removeAssignees

removeAssignees()

Removes all assignees from the workitem.

Example:
The following script removes all existing assignees from a work item and adds the user whose ID is jocelynb as the sole assignee.

var wi = getWorkItem(); wi.removeAssignees(); wi.addUserAssignee("jocelynb");

resume

This function reactivates a suspended work item. If the work item is assigned to more than one user, the work item's state is set to running. If there is only one assignee, the work item's state is set to active.

Example:

var wi = getWorkItem();

if( wi.isStateRunning() )

{

   wi.resume(); //resume work item immediately

   if( wi.isStateRunning() )

      java.lang.System.out.println( "Work item is assigned to a group: );

   else

      java.lang.System.out.println( "work item is assigned to one user" );

}

setExpirationDate

Sets the expiration date of the work item. If the work item has expired, use the extend() function instead of setExpirationDate() to extend the expiration date, since extend() removes the expired flag and setExpirationDate() does not.

Parameters

expDate

Date object for the expiration date for the work item.

Example:

var wi = getWorkItem();

var now = new Date();

//Set expiration date to 1 hour in the future

var expDate = new Date( now.getTime() + (1 * 60 * 60 * 1000)

);

wi.setExpirationDate( expDate );

suspend

This function makes the work item inactive. Users cannot work with the work item until it has been resumed through Process Administrator or via a call to resume().

Example:

var wi = getWorkItem();

wi.suspend();

if( wi.isStateSuspended() )

   wi.resume(); //resume the work item immediately

ContentStore

---

Scripts can use the global function getContentStore() to get a contentStore object connected to the content store of the application. There are three different ways to call the function:

• getContentStore ();

  Without parameters, this function returns the content store defined by the application. The returned object is configured with the URL, username, and password that are specified in Process Builder.

• getContentStore (httpURL, username, password);

  When called with the above three parameters, getContentStore() creates a new content store with the specified parameters passed in. The returned object is a content store rooted at the specified httpURL. The content store uses the username and password to authenticate against.

• getContentStore (httpURL, username, password, timeout);

  This form is identical to the previous form except for an additional timeout, specified in seconds, on HTTP connections.

The following methods can be called on the contentStore object:

copy	getContent	list
download	getException	mkdir
exists	getSize	move
getBaseURL	getStatus	remove
getBaseURL	getVersion	rmdir
getBaseURL	initialize	store
getRootURL	isException	upload

copy

copy(srcURL, dstURL)

Copies the content at the srcURL to the dstURL. Both URLs have to be on the same content store. If dstURL already exists, it is overwritten.

Parameters

srcURL	A String of an HTTP URL or URI of the content in the content store object.
dstURL	A String of an HTTP URL or URI of the content in the content store object.

Example:

var cs = getContentStore();

var result = cs.copy( cs.getBaseURL ( "shopping/documents" ) + "myFile.html",

cs.getBaseURL ( "shopping/old" ) + "myFile.html" ) ;

var httpcode = cs.getStatus ( result );

if (httpcode == 200)

{

}

download

download(url, file)

Downloads the content at the url into the specified file. If a username and password is specified for this content store, they are used in the request to retreive the content.

Parameters

url	A String of an HTTP URL or URI of the content in the content store object.
file	File where the content is stored; if exists, it will be overwritten.

Example:

var cs = getContentStore();

var result = cs.download ( cs.getBaseURL() + "myFile.html" , "C:/myFile.html" );

var httpcode = cs.getStatus( result );

if (httpcode == 200)

{

// it went OK ...

}

exists

exists(url)

Checks if the URL exists on the content store.

Parameters

url	A String of an HTTP URL or URI of the content in the content store object.

Example:

var cs = getContentStore();

var result = cs.exists( cs.getBaseURL ( "shopping/documents" ) + "myFile.html" );

var httpcode = cs.getStatus ( result );

if (httpcode == 200)

{

// it exists OK ...

}

getBaseURL

getBaseURL()

Returns the root URL of this content store.

See getRootURL for examples.

getBaseURL

getBaseURL(path)

Returns a base container url which includes the path as postfix to the content store root url.

Parameters

path	A String of the relative path segment.

Example:

var cs = getContentStore();

java.lang.System.out.println("ContentStore ROOT URL " + cs.getBaseURL("shopping/documents"));

getBaseURL

getBaseURL(path, instanceid)

Returns a base container URL which includes the path and the instanceid as postfix to the content store root URL.

Parameters

path	A String of a relative path segment.
instanceid	An integer instance id of the process.

Example:

var pi = getProcessInstance();

var cs = getContentStore();

java.lang.System.out.println("ContentStore ROOT URL " + cs.getBaseURL("shopping/documents", pi.getInstanceId() ));

getContent

getContent (url)

Returns a String of the content at the specified url, where url describes either an HTTP URL or URI of the content in the content store object. A URI is a path segment only, specified as an absolute or relative pathname.

Parameters

url	A String of an HTTP URL or URI of the content in the content store object.

On an HTTP content store, getContent( ) is implemented as a GET request against the server. If a username and password have been specified for this content store, they will be used in the request to retrieve the content.

If the content cannot be retrieved or doesn't exist, getContent( ) returns null. Call the exists( ) method to check whether the URL exists in the content store. See also store( ) and upload( ).

Example:

var cs = getContentStore(); // Relative URI var content = cs.getContent ( "myFile.html" ); // Absolute URI var content = cs.getContent ( "/CS/CheckOut/basket.xml" ); // If URL, then the host and port portion of the URL must be // that of the content store URL. This is typically returned // by the getBaseURL() method. var content = cs.getContent ( cs.getBaseURL() +    "CheckOut/basket.xml" )

getException

getException(result_string)

Gets the exception in string format that has occured in the operation move(), copy(), upload(), download(), store(), exists(), initialize(), remove(), mkdir(), rmdir().

Parameters

result_string

A String of the results from one of the methods listed above.

Example:

var cs = getContentStore();

// remove a file from the content store

var result = cs.remove(cs.getBaseURL ( "shopping/documents" ) + "myFile.html" );

if ( cs.isException (result))

{

// if something went wrong, print out the exception

java.lang.System.out.println("Exception: " +

      cs.getException (result));

}

getRootURL

getRootURL ()

Returns a string of the root URL of the content store, including the ending /. This is a string version of the URL for the content store as specified in Process Builder.

Example:

var cs = getContentStore();

java.lang.System.out.println("ContentStore ROOT URL " + cs.getRootURL());

getSize

getSize(url)

Returns the size in bytes of the content of the specified URL at the content store. On any error, -1 is returned.

Note that in certain rare circumstances, the length of the content of such a URL cannot be established.

Parameters

url	A String of an HTTP URL or URI of the content in the content store object.

Example:

var cs = getContentStore();

var result = cs.getSize( cs.getBaseURL ( "shopping/documents" ) + "myFile.html" );

if (result < 0)

{

}

getStatus

getStatus(result)

Returns the status of the last successful Content Store operation by one of the methods: move(), copy(), upload(), download(), store(), exists(), initialize(), remove(), mkdir(), rmdir().

Parameters

result

A String of the results of one of the methods listed above.

Example:

var cs = getContentStore();

var result = cs.remove( cs.getBaseURL ( "shopping/documents" ) + "myFile.html" );

if ( cs.getStatus(result) != 200)

{

}

getVersion

getVersion()

Returns the version string of the the ContentStore implementation. Currently, this value is 0.1999100221-001.

Example:

var cs = getContentStore();

java.lang.System.out.println("ContentStore Version " + cs.getVersion());

initialize

initialize(url)

Initializes the URL with basic content so the URL exists on the Content Store. This method returns either the status code from the content store for the operation or an exception. Note that no exception is actually thrown. To see if an exception is returned, call isException() on the return value from this method and call getStatus() to get the numeric HTTP protocol status of this content store request.

Parameters

url	A String of an HTTP URL or URI of the content in the content store object.

Example:

var pi = getProcessInstance();

var cs = getContentStore();

var result = cs.initialize ( cs.getBaseURL ( "shopping/documents" ) + "myFile.html" );

var httpcode = cs.getStatus ( result );

if (httpcode == 201 || httpcode == 204)

{

}

else

{

}

isException

isException(exception)

Checks if the result string from move(), copy(), upload(), download(), store(), exists(), initialize(), remove(), mkdir(), rmdir() is an exception.

Parameters

exception

A String of the results of one of the methods of Content Store that can return an exception.

Example:

var cs = getContentStore();

var result = cs.remove( cs.getBaseURL ( "shopping/documents" ) + "myFile.html" );

if ( cs.isException ( result ))

{

}

else if ( cs.getStatus ( result ))

{

}

list

list(url)

Gets the container content (folder) listing of this content store container.

Parameters

url	A String of an HTTP URL or URI of the content in the content store object.

mkdir

mkdir (URLString)

Creates the appropriate folder structure on the web server being used as the content store. The URLString must be a full path name to the new directory. If the specified directory already exists, nothing happens.

Parameters

URLString

A String of an HTTP URL or URI of the content in the content store object.

Example:

var cs = getContentStore();

var result = cs.mkdir( cs.getBaseURL ( "shopping/documents" ) );

var httpcode = cs.getStatus ( result );

if (httpcode == 200)

{

}

move

move (URLString1, URLString2)

moves the file from the URLString1 to URLString2, overwriting any file that already exists at the destination file name. If the file to be moved URLString1, does not exist, this function gives an error.

Both file names must be full pathnames. The following code moves the file tempdoc.html from the temp directory to doc1.html in the docs directory on the web server pm.company.com.

Example:

var myStore = getContentStore ();

var pi = getProcessInstance ();

var pid = pi.getInstanceId();

myStore.move("http://pm.company.com/temp/tempdoc.html",

      "http://pm.company.com/docs/doc1.html");

Note that the move() function does not create directories -- use mkdir() to create a directory before moving a file to it.

remove

remove(url)

Deletes the content at the specified URL.

Parameters

url	A String of an HTTP URL or URI of the content in the content store object.

Example:

var cs = getContentStore();

var result = cs.remove( cs.getBaseURL ( "shopping/documents" ) + "myFile.html" );

var httpcode = cs.getStatus ( result );

if (httpcode == 200)

{

}

rmdir

rmdir(url)

Removes the container (folder) at the specified URL. The folder must be empty to be removed or an error is returned.

Parameters

url	A String of an HTTP URL or URI of the content in the content store object.

Example:

var cs = getContentStore();

var result = cs.rmdir( cs.getBaseURL ( "shopping/documents" ) );

var httpcode = cs.getStatus ( result );

if (httpcode == 200)

{

}

store

store (content, url)

Stores the content specified by content in the given url. If a username and password has been specified for this content store, they are used in the request to store the content.

Parameters

content	A String of the content to store in the content store as this URL.
url	A String of an HTTP URL or URI of the content in the content store object.

Example:

var cs = getContentStore();

var content = "<body><b>Hello</b> world ... </body>";

// Relative URI

var result = cs.store ( content, "myFile.html" );

// Absolute URI

var result = cs.store ( content, "/CS/myFile.html" );

// Absolute URL (for historical reasons)

var result = cs.store ( content, cs.getBaseURL () + "myFile.html" );

upload

upload(file, url)

Uploads the file content to the URL specified. If a username and password has been specified for this content store, they are used in the request to upload the file.

Parameters

file	File to upload.
url	A String of an HTTP URL or URI of the content in the content store object.

Example:

var cs = getContentStore();

var result = cs.upload ( "C:/myFile.html", cs.getBaseURL() + "myFile.html" );

var httpcode = cs.getStatus( result );

if (httpcode == 201 || httpcode == 204)

{

}

CorporateDirectory

---

Scripts can use the global function getCorporateDirectory() to get a corporateDirectory object that is connected to the corporate directory in the Directory Server for the cluster.

Example:

var corp = getCorporateDirectory ();

Scripts can then use the corporateDirectory object to access and modify information about users in the corporate directory.

The following methods can be called on the corporateDirectory object:

addUser	getUserByCN	modifyUserByCN
deleteUserByCN	getUserByDN	modifyUserByDN
deleteUserByDN	getUserById	modifyUserById
deleteUserById

addUser

addUser (userDN, attributes, objectClasses)

Adds a user to the directory. The user's Distinguished Name (DN) is specified by userDN. The attributes for the user are specified as a JavaScript associative array indexed by attribute name. The objectClasses parameter specifies any additional object classes as a JavaScript array. If the addition of the user is successful, returns true, otherwise returns false.

userDN	A String of the distinguished name (DN) for the new user entry.
attributes	An Object that is a table of key/value pairs specifying user attributes.
objectClasses	An Array of object classes with which the user entry is compliant.

Example:

var attrs = new Object(); attrs[ "uid" ] = "joe"; attrs[ "cn" ] = "Joe Cool"; attrs[ "sn" ] = "Cool"; attrs[ "mail" ] = "joe@acme.com"; attrs[ "favoriteColor" ] = "green"; // Specify additional objectclasses var OCs = new Array( "favoriteColorOC" ); if( cd.addUser( "uid=joe, ou=People, o=acme.com", attrs, OCs ) == false ) { java.lang.System.out.println( "Problems adding user entry joe" ); }

deleteUserByCN

deleteUserByCN(userCN)

Deletes the user entry specified by the Common Name (CN) userCN from the corporate directory. Returns true if the deletion is successful. Returns false if the deletion failed.

userCN

A String of the common name (CN) for the user entry to be deleted.

Example:

var cd = getCorporateDirectory(); var joe = cd.getUserById( "joe" ); if( cd.deleteUserByCN( joe.cn ) )    java.lang.System.out.println( "User entry joe deleted" ); else    java.lang.System.out.println( "Problems deleting user entry joe" );

deleteUserByDN

deleteUserByDN(userDN)

Deletes the user entry specified by the Distinguished Name (DN) userDN from the corporate directory. Returns true if the deletion is successful. Returns false if the deletion failed.

userDN

A String of the distinguished name (DN) for the user entry to be deleted.

Example:

var cd = getCorporateDirectory();

var joe = cd.getUserById( "joe" );

if( cd.deleteUserByDN( joe.getDN ) )

   java.lang.System.out.println( "User entry joe deleted" );

else

   java.lang.System.out.println( "Problem deleting user entry joe" );

deleteUserById

deleteUserById(uid)

Deletes the user entry specified by userID from the corporate directory. Returns true if the deletion is successful. Returns false if the deletion failed.

userDN

A String of the DN for the user entry to be deleted

Example:

var cd = getCorporateDirectory(); var joe = cd.getUserById( "joe" ); if( cd.deleteUserByCN( joe.getUserId() ) )    java.lang.System.out.println( "User entry joe deleted" ); else    java.lang.System.out.println( "Problem deleting user entry joe" );

getUserByCN

getUserByCN(userCN)

Returns the user entry corresponding to the Common Name (CN) userCN as a JavaScript User object. User object is a Process Manager-specific object. Returns null if no user entry corresponds to userCN.

userCN

A String of the common name (CN) of the user entry to be retrieved .

Example:

var cd = getCorporateDirectory(); var joe = cd.getUserByCN( "Joe Cool" ); if( joe == null )    java.lang.System.out.println( "Cannot find entry for user joe" ); else    java.lang.System.out.println( "Found user joe" );

getUserByDN

getUserByDN (userDN)

Returns the user entry corresponding to the Distinguished Name (DN) userDN as a JavaScript User object. User object is a Process Manager-specific object. Returns null if no user entry corresponds to userDN.

userDN

A String of the distinguished name (DN) of the user entry to be retrieved.

Example:

var cd = getCorporateDirectory(); var joe = cd.getUserByDN( "uid=joe, ou=People, o=acme.com" ); if( joe == null )    java.lang.System.out.println( "Cannot find entry for user joe" ); else    java.lang.System.out.println( "Found user joe" );

getUserById

getUserById (uid)

Returns the user entry corresponding to the user id userId as a JavaScript User object. The User object is a Process Manager-specific object. Returns null if no user entry corresponds to userId.

uid	A String of the User ID for the user entry to be retrieved.

Example:

var cd = getCorporateDirectory(); var joe = cd.getUserByID( "joe" ); if( joe == null )    java.lang.System.out.println( "Cannot find entry for joe" ); else    java.lang.System.out.println( "Found user joe" );

modifyUserByCN

modifyUserByCN (userCN, attrName, attrValue, operation)

See modifyUserByDN.

userCN	A String of the common name (CN) of the user entry to be modified.
attrName	A String of the name of the user entry attribute to modify.
attrValue	A String of the value of the user entry attribute to modify.
operation	A String of the modification operation to be performed.

Example:

var cd = getCorporateDirectory(); if (cd.modifyUserByCN("uid=joe, ou=People, o=acme.com",    "favoriteColor", "blue", "ADD" ) == false ) {    java.lang.System.out.println("Failed to modify user joe"); } else if ( cd.modifyUserByCN( "uid=joe, ou=People, o=acme.com",    "favoriteColor", "red", "REPLACE" ) == false ) {    java.lang.System.out.println( "Failed to modify user joe"); } else if( cd.modifyUserByCN( "e, ou=People, o=acme.com",    "favoriteColor", "", "DELETE" ) == false ) {    java.lang.System.out.println( "Failed to modify user joe"); }

modifyUserByDN

modifyUserByDN (userDN, attrName, attrValue, operation)

Modifies the user entry specified by the Distinguished Name (DN) userDN in the corporate directory. Returns true if the modification is successful. Returns false if the modification fails.

userDN	A String of the distinguished name (DN) of the user entry to modify.
attrName	A String of the name of the user entry attribute to modify.
attrValue	A String of the value of the user entry attribute to modify.
operation	A String of the modification operation to perform.

The type of modification is specified by the operation, which can have the following values:

ADD: adds the attribute attrName with the value attrValue to the user entry. If attrName has multiple values, the operation can result in multiple instances of attrName in the user entry. attrName should be a valid attribute of one of the object classes with which the user entry complies.

REPLACE: replaces the value currently associated with attrName with the new value attrValue.

DELETE: deletes attrName from the user entry.

Example:

var cd = getCorporateDirectory(); if (cd.modifyUserByDN( "uid=joe, ou=People, o=acme.com",    "favoriteColor", "blue", "ADD" ) == false ) {    java.lang.System.out.println("Failed to modify user joe"); } else if ( cd.modifyUserByDN( "uid=joe, ou=People, o=acme.com",    "favoriteColor", "red", "REPLACE" ) == false ) {    java.lang.System.out.println( "Failed to modify user joe"); } else if ( cd.modifyUserByDN( "e, ou=People, o=acme.com", "favoriteColor", "", "DELETE" ) == false ) {    java.lang.System.out.println( "Failed to modify user joe"); }

modifyUserById

modifyUserById (userID)

See modifyUserByDN.

userID

String

A String of the User ID of the user entry to modify.

Example:
See modifyUserByDN. You must pass in a user ID rather than a DN.

User

---

The User object has publically accessible methods and exposes the user attributes making up an LDAP user entry. You can treat the User object as a hashtable of attribute key/value pairs where the keys are the attribute names as they apear in the LDAP entry. In the following code sample, you can also access the attribute favoritecolor, which is an attribute available from the user joe's entry.

Example:

var cd = getCorporateDirectory(); var u = cd.getUserById( "joe" ); java.lang.System.out.println( "Joe's email is " + u.mail ); java.lang.System.out.println( "Joe's favorite color is " + u.favoritecolor );

The following methods can be called on the User object:

getUserId

getUserId

getUserId()

Returns the user ID for the current user. The user ID attribute can also be accessed directly as the id property of the user object.

Example:

var cd = getCorporateDirectory(); var u = cd.getUserByDN( "uid=joe, ou=People, o=acme.com" ); java.lang.System.out.println( "Joe's user id is " +    u.getUserID() ); var pi = getProcessInstance(); u = pi.getCreatorUser(); java.lang.System.out.println( "Creator's user id is " +    u.getUserId() );

Logging and Error Handling Global Functions

---

The following global functions are available for adding entries to error, informational, and history logs. Note that the two forms, Msg and Message, are identical. The duplicate names are provided for convenience only.

logErrorMsg or logErrorMessage

logHistoryMsg or logHistoryMessage

logInfoMsg or logInfoMessage

logSecurityMsg or logSecurityMessage

setErrorMsg or setErrorMessage

logErrorMsg

logErrorMsg (label, context)

Adds an entry in the error log of the application. This information is displayed to the administrator when viewing the error log.

label	String of the label for the error log's entry.
context	(Optional) Object that is a Hashtable of key/value pairs to print in the log entry.

The following code could be used in a completion script or automation script to log an error message when a user tries to submit a document for review when the document is too long.

Example:

// LOG AN ERROR MESSAGE var pi = getProcessInstance(): var author = pi.getData("author"); var docName = pi.getData("docName"); var pageCount = parseInt (pi.getData("pageCount")); if (pageCount > 5000) {    var error1 = new Object ();    error1.author = author;    error1.docName = docName;    error1.pageCount = pageCount;    logErrorMsg ("PAGE_COUNT_TOO_LONG", error1); }

logHistoryMsg

logHistoryMsg (label, comment)

Adds a row in the history log. This information is displayed to users when viewing Details & History in a work item list.

label	String of the label for the entry in the history log.
comment	(Optional) String of an additional comment for the history event.

The label is a string to be used as the label for the entry in the history log, and the optional argument comment is a string describing the entry.

Use this function to add information for the users about the work items. The following code could be used in a completion script to add details when an author submits a document for review.

Example:

// LOG A HISTORY MESSAGE var pi = getProcessInstance(): var author = pi.getData("author"); var docName = pi.getData("docName"); var pageCount = parseInt (pi.getData("pageCount")); logHistoryMsg ("Doc Submitted for Review",    " \nAuthor: " + author +    " \nDocument name: " + docName +    " \nPage count: " + pageCount);

logInfoMsg

logInfoMsg(label, context)

Adds an entry in the info log of the application. This information is displayed to the administrator when they view the info log.

label	String of the label for the entry in the history log.
context	(Optional) Object that is a hashtable of key/value pairs to print in the log entry.

The label is a string to be used as the label for the entry in the info log, and the optional argument context is an object that has a variable for each property of the info message.

Use this function to show information about the execution of scripts. This is particularly useful for viewing the progress of script execution while debugging scripts. The following code could be used in a completion or automation script to log information about a document that has been submitted for review.

Example:

// LOG AN INFO MESSAGE var pi = getProcessInstance(): var author = pi.getData("author"); var docName = pi.getData("docName"); var pageCount = parseInt (pi.getData("pageCount")); var info1 = new Object (); info1.author = author; info1.docName = docName; logInfoMsg ("DOC_SUBMITTED_FOR_REVIEW", info1);

logSecurityMsg

logSecurityMsg (label, context)

Adds an entry in the security log of the application. This information is displayed to the administrator when they view the security log.

label	String of the label for the entry in the security log.
context	(Optional) Object that is a hashtable of key/value pairs to print in the log entry.

The label is a string to be used as the label for entry in the security log, and the optional argument context is an object that has a variable for each property of the error message.

The following code could be used in a completion script or automation script to log a warning when an unauthorized user tries to perform a task that accesses an external database.

Example:

// LOG A SECURITY MESSAGE var pi = getProcessInstance(): var username = pi.getData("username"); var password = pi.getData("password"); var externalDB = pi.getData("externalDBName"); var securityError1 = new Object (); securityError1.username = username; securityError1.password = password; securityError1.externalDB = externalDB; logSecurityMsg ("EXTERNAL_DB_ACCESS_NOT_ALLOWED", securityError1);

setErrorMsg

setErrorMsg (errMessage)

This function enables the designer to add additional information that describes why a script failed. This information is displayed to the participant as part of the error dialog box.

errMessage

String that is added to the error dialog box when an error occurs during processing.

The following code could be used in a completion script to add a message explaining that the completion script failed because the submitted document has too many pages.

Example:

function checkPageCount () { // ADD A COMPLETION SCRIPT ERROR MESSAGE var pi = getProcessInstance(): var docName = pi.getData("docName"); var pageCount = parseInt (pi.getData("pageCount")); if (pageCount > 5000) {    setErrorMsg ("The page count for " + docName +       " is " + pageCount +       " which exceeds the maximum page count allowed. " +    " Did you really write such a long document?");    return false;    }    else return true; }

Assignment, Completion, and Email Scripts

---

This section lists the predefined assignment, completion, and email scripts available in Process Automation Edition. These predefined scripts (which are also global functions) can be called from other scripts. For example, an expiration handler script could call the predefined function toUserById(). The value returned by toUserById() could in turn be passed to the assignTo() method on a work item. The assignTo() method would then re-assign the work item to a user with a given user ID.

The global functions in this section are:

checkParallelApproval	toCreator
defaultNotificationHeader	toGroup
defaultNotificationSubject	toManagerOf
emailById	toManagerOfCreator
emailOfAssignees	toManagerOfRole
emailOfCreator	toParallelApproval
emailOfRole	toUserById
randomToGroup	toUserFromField

checkParallelApproval

checkParallelApproval (dataField, stopAction)

This function is meant for use as a completion script for work items that use the toParallelApproval() assignment script. The dataField must be the name of the data field that was specified in toParallelApproval(), and is used to keep track of who has completed the work item so far. The stopAction is the name of the action that a user can take to stop the approval process.

dataField	String of the name of a data field.
stopAction	String of the name of an action.

If an activity (work item) uses the toParallelApproval() assignment script, the activity should have two possible actions for the assignees to take when they complete the work item. One should indicate approval, and the other should indicate disapproval. The activity should also use the checkParallelApproval() completion script, which performs the "disapproval' action as soon as any one assignee selects it, the theory being that it takes everyone to approve the work item, but only one dissenter to disapprove it.

Example:

checkParallelApproval( "trackerField", "Reject" );

defaultNotificationHeader

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.

Example:

function emailBody( ) { var body = "Email message body <br>"; body += defaultNotificationHeader(); return body; }

defaultNotificationSubject

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.

Example:

function emailSubject( ) { var subject = "Subject: " + defaultNotificationSubject(); return subject; }

emailById

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.

userId

String of the User Id whose email address is to be returned.

Example:

emailById( "joe" );

emailOfAssignees

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.

Example:

emailOfAssignees();

emailOfCreator

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.

Example:

var pi = getProcessInstance(); var creatorEmail = emailOfCreator(); pi.setData( "creatorEmail", creatorEmail );

emailOfRole

emailOfRole(roleName)

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.

roleName

String of a role name

Example:

emailOfRole( "reviewer" );

randomToGroup

randomToGroup(groupName)

This function returns an array containing a user ID of one member of the group. The group member is selected at random. This function is intended to be used as an assignment script but can be used anywhere that an array of user IDs is needed.

groupName

String of the name of a group.

Example:

var userArray = randomToGroup( "helpDesk" );

toCreator

toCreator()

Returns a JavaScript array with the user ID of the user who created the process instance. This method is the default assignment script assigned to user activities when a node is created on the Process Map.

Example:

var creatorArray = toCreator(); java.lang.System.out.println( "Creator is " + creatorArray[ 0 ]);

toGroup

toGroup(groupName)

Returns a JavaScript array of user IDs of all members of the specified group. If the parameter groupName does not correspond to an actual group in the application's Groups and Roles folder, returns null.

groupName

String of the name of the group.

Example:

var groups = toGroup( "reviewers" ); if( groups != null ) {    java.lang.System.out.println("Number of members in group: " +          groups.length );    for (var i = 0; i <= groups.length; i++)    {          java.lang.System.out.println( "Member #" +             i + ": " + groups[i ] );    } } else   java.lang.System.out.println( "There is no reviewers group" );

toManagerOf

toManagerOf (userId)

This function returns an array containing the user ID of the manager of the user with the given user ID. The manager attribute of the given user must contain a DN in the corporate user directory. This function is intended to be used as an assignment script but can be used anywhere that an array of user IDs is needed.

userId

A String of a user ID.

Example:

var managerArray = toManagerOf( "mike" ); java.lang.System.out.println( "Manager of user mike is: " +    managerArray[0] );

toManagerOfCreator

toManagerOfCreator()

This function returns an array containing the user ID of the manager of the creator of the process instance. The manager attribute of the creator user must contain a DN in the corporate user directory. This function is intended to be used as an assignment script but can be used anywhere that an array of user IDs is needed.

Example:

var managerArray = toManagerOfCreator(); java.lang.System.out.println( "Manager of the process creator is: " + ManagerArray[ 0 ] );

toManagerOfRole

toManagerOfRole(role)

This function returns an array containing the user ID of the manager of the user defined as the given role. The manager attribute of the user fulfilling the role must contain a DN in the corporate user directory. This function is intended to be used as an assignment script but can be used anywhere that an array of user IDs is needed.

role	String of a name of the role.

Example:

var managerArray = toManagerOfRole( "reviewer" ); java.lang.System.out.println( "Manager of the reviewer is: " + managerArray[ 0 ] );

toParallelApproval

toParallelApproval(arrayOfUserDNs, dataField)

This function should be used as an assignment script to assign a work item to several users who must all complete the work item. The arrayOfUsers argument is an array of user IDs, and dataField is a data field that keeps track of who has performed the work item and who still needs to do it. This field is a computed field of length 2000 that must add to the data dictionary.

arrayOfUsers	Array of user IDs.
dataField	String of a name of a data field in the current process.

If an activity (work item) uses the toParallelApproval() assignment script, the activity should have two possible actions for the assignees to take when they complete the work item. One action should indicate approval, and the other should indicate disapproval. The activity should also use the checkParallelApproval() completion script, which performs the "disapproval" action as soon as any one assignee selects it. The idea is that it takes everyone to approve the work item, but only one dissenter to disapprove it.

Example:

var cd = getCorporateDirectory(); var user1 = cd.getUserById( "user1" ); var user2 = cd.getUserById( "user2" ); var user3 = cd.getUserById( "user3" ); var approvers = new Array( user1, user2, user3); toParallelApproval( approvers, "trackerField" ); toParallelApproval(toGroup( "approvers" ), "trackerField" );

toUserById

toUserById(userId)

This function returns an array containing the user ID of the user with the given user ID. This function is intended to be used as an assignment script but can be used anywhere that an array of user IDs is needed.

userId

String of a user ID.

Example:

var userArray = toUserById( "sijacic" );

toUserFromField

toUserFromField(dataField)

This function returns an array containing the user IDs of the user whose user ID is the value of the given data field. This function is intended to be used as an assignment script but can be used anywhere that an array of user IDs is needed.

dataField

String of a name of a data field wbose value is a user ID.

Example:

var userArray = toUserFromField( "approver" ); java.lang.System.out.println("The approver is: " + userArray[0]);

Miscellaneous Global Functions

---

This section summarizes the global functions that are neither log and error functions nor predefined scripts.

The global functions in this section are:

	getProcessInstance
ejbLookup	getSubProcessInstance
evaluateTemplate	getWorkItem
expireIn	__includeFile
getAction	mapTo
getApplicationName	mount
getApplicationPath	setConnector
getApplicationPrettyName	__setIncludePath
getBaseForFileName	setRedirectionURL
getConnector	url_OnDisplayHistory
getContentStore ()	url_OnDisplayProcessInstance
getCreatorUserId	url_OnDisplayWorklist
getCorporateDirectory	url_OnListApplications
__getIncludePath	url_OnListEntryNodes
getJndiNamingContext

ejbLookup

ejbLookup(jndiName)

Looks up an EJB that can be found under the given JNDI name. If no EJB exists under this name, an EJB exception, javax.naming.NamingException, is thrown. Process Manager handles this exception by moving the process instance into the designated Exception Manager node.

If the bean can be found under the given JNDI name, the home interface of that bean is returned. The home interface is used to create new instance of the EJB or find existing instnaces of the given EJB. The definition of the home interface is completely application-dependent; it typically consists of several create() and finder() methods. This function call is equivalent to the getJndiNamingContext().lookup(jndiName) function call.

jndiName

A String of the JNDI name of the EJB to look up.

Example:

var home = ejbLookup("Netscape/CreditCardServer"); // Create a credit card server that can do card authorizations. var creditCardServer = home.create ( "mastercard" );

evaluateTemplate

evaluateTemplate(templateName)

Used primarily in email notifications, but can be used for any template-like evaluation.

For email notifications, use evaluateTemplate() in the email body. When you create an email notification in Process Builder, specify evaluateTemplate( "templateFile" ) as the body script, where templateFile is the name of the template file relative to the application directory on the server. From Process Builder, you should include your template files in a folder called templates, a directory located in the application directory of Process Builder. When you deploy, the same directory structure is replicated on the server.

evaluateTemplate() also evaluates JavaScript segments contained in the template file. These segments are identified by <script language="Rhino"> tags.

In an HTML page containing client-side JavaScript, you can replace

<script language="JavaScript">

with

<script language="Rhino">

The Process Manager engine will evaluate the JavaScript in the same manner the browser does.

You can access the entire engine API (e.g., getProcessInstance(), getWorkITem(), etc.) from within these segments. To send output to an HTML file, use document.write() with the output you want to send provided as an argument.

evaluateTemplate() returns a string. The string is made up of the contents of the template file with the Rhino segments evaluated. If there are no Rhino segments in the file, the string simply contains the file contents. If there are Rhino segments, the string contains the evaluated JavaScript rather than the Rhino segments.

Example:

var fileContents = evaluateTemplate( "templateFile" ); var cs = getContentStore(): cs.upload( fileContents, url ):

expireIn

expireIn(val, unit)

Returns a JavaScript Date object set to the absolute datetime when the current work item expires.

val	An Integer specifying the number of units in which to expire the workitem.
unit	A String that specifies the unit of time measurement, such as minutes or hours.

This function is normally used to specify the expiration time for a particular activity, and is usually set by the designer through Process Builder. In the event that you choose to specify the arguments for this function manually, the parameter unit can contain the following values:

• minutes

• hours

• days

• weeks

• months

Note that a month is presumed to contain 30 days. Asking a work item to expire one month from the date January 1st results in an expiration date of January 30th, not February 1st.

Example:

expireIn( 6, "minutes" ); // expire in 6 minutes expireIn( 30, "days" ); // expire in 30 days expireIn( 1, "month" ); // expire in 30 days

getAction

getAction()

Returns the name of the Activity followed by a dot ('.') and then the name of the transition (button), for example, getApproval.approved.

The action name corresponds to the name of the button clicked when the work item form is submitted. This function can be used in any script, but is best used from the completion script of a user activity.

Example:

function completion( ) {    var pi = getProcessInstance();    pi.setData( "submittedAction", getAction() ):    return true; }

getApplicationName

getApplicationName()

Returns the name of the application (for example: "DataSheet") as a string.

Example:

var appName = getApplicationName(); java.lang.System.out.println( "The application name is: " + appName );

getApplicationPath

getApplicationPath()

Returns the pathname of the directory containing the files for this application as a string.

Example:

var appPath = getApplicationPath(); java.lang.System.out.println( "The application path is: " + appPath );

getApplicationPrettyName

getApplicationPrettyName()

Returns the pretty name of the application (for example: "DataSheet Management") as a string.

Example:

var appPN = getApplicationPrettyName(); java.lang.System.out.println( "The application pretty name is: " + appPN );

getBaseForFileName

getBaseForFileName (processId)

Given a unique process instance ID, this function returns a string of the base file name for the content store for that process instance.

processId

A String of the process instance ID.

The following code creates a path name for the file myFile.html in the content store. Note that this code does NOT create the file, it simply creates a string that can be used as the file name by methods on a contentStore object, such as move() and store().

Example:

var pi = getProcessInstance(); var pid = pi.getInstanceId(); var contentStorePath = getBaseForFileName (pid); var newFileName = contentStorePath + "myFile.html";

getConnector

getConnector(connectorKey)

Given a connector key, returns a connector object from the list of connector objects available for use by scripts.

connectorKey

A String specifying a connector ID (previously set by setConnector()).

Example:

function initialisationScript( ) {    var c = new Packages.com.acme.DBConnection();    setConnector( "dbConnector" );    return true; } var c = getConnector( "dbConnector" );

getContentStore ()

getContentStore ()

getContentStore(httpURL,user,password)

Returns a contentStore object connected to the content store. If no arguments are passed, this method gets the content store associated with the current application.

If httpURL, user and password arguments are provided, this method returns a content store object connected to the given URL.

You must have a content store object to use any of the content store methods.

httpURL	A String of the URL of an HTTP server capable of acting as a content store.
user	A String of the User ID of the user who will authenticate the content store specified by httpURL.
password	Password for the specified user.

Example:

var cs = getContentStore(); var publishCS = getContentStore( "http://publish.netscape.com/CS", "sijacic", "password");

getCreatorUserId

getCreatorUserId ()

Returns the user ID for the creator user of the current process instance.

This function is intended to be used as the initiate-as script for sub-process nodes. When the child process instance is created, its creator must be determined. Normally, the creator of the child process instance is the same user that authenticated with the server at the time the sub-process node was executed. However, it may be desirable (or necessary) to set the child creator to the same user as the creator of the parent process instance.

If you choose to use this function to change the child creator user, the authenticating (or current) user must be a member of the trusted users group in the child application.

Example:

var pi = getProcessInstance(); var creatorUser = pi.getCreatorUser(); var creatorUserId = creatorUser.getUserId();

getCorporateDirectory

getCorporateDirectory ()

Returns a corporateDirectory object connected to the corporate directory in the Directory Server. See the section "CorporateDirectory" for details of the methods on this object.

Example:

var corpDir = getCorporateDirectory();

__getIncludePath

__getIncludePath ()

Returns the current inclusion path used by the server to search for JavaScript source files. This search path resembles in behavior the PATH mechanism used in Windows NT and UNIX to search for executables and libraries when a file name is not absolute.

The directory installDir/resources/server/js (where installDir is Process Manager installation directory on the server machine) is included in the search path by default.

Example:

// Returns the current search path var includePath = __getIncludePath(); // Add our own directory to the search path includePath += ';' + "d:\\tmp"; // Set the search path __setIncludePath( includePath );

getJndiNamingContext

getJndiNamingContext()

Returns the current iAS JNDI naming context used to look up the home interface of an EJB.

Use this function to access EJBs from within a Custom Activity. You can pass the instance of the naming context to the Custom Activity and use the lookup() method on this context to obtain home interfaces of the beans.

Example:

var namingContext = getJndiNamingContext()

getProcessInstance

getProcessInstance ()

Returns a JavaScript ProcessInstance object associated with the current work item.

See the section ProcessInstance for details of the methods on this object.

Example:

var wi = getWorkItem(); var pi = getProcessInstance(); java.lang.System.out.println( "The Process Instance ID: " + pi.getInstanceId() );

getSubProcessInstance

getSubProcessInstance ()

Returns a ProcessInstance object corresponding to the completed child process instance. This function should only be used from the completion script of a sub-process node. The object returned by this function has all the same methods expected of a ProcessInstance object, except that the information contained within corresponds to the completed child process instance instead of the parent. If this function is called from any location other than the completion script of a sub-process node, null is returned.

Example:

// Completion script of sub-process node function parentCompletion( ) { var pi = getProcessInstance(); // parent process instance var spi = getSubProcessInstance(); // child process instance // Map some of the data elements from the child back to the // parent process instance pi.setData( "childStatus", spi.getData( "status" ) ); pi.setData( "numApprovers", spi.getData( "numApprovers" ) ); return true; }

getWorkItem

getWorkItem ()

Returns a workItem object that represents the current work item. See the section WorkItem for details of the methods on this object.

Example:

var wi = getWorkItem();

__includeFile

__includeFile (fileName)

Reads in the contents of a JavaScript source file and evaluates the contents. Any JavaScript functions and objects defined within the file are available to all user scripts.

The function __includeFile() and its "helper" functions, __getIncludePath() and __setIncludePath(), are used by the server to define the built-in JavaScript functions available to user scripts.

If you want to access JavaScript functions or objects from user scripts and do not want to include the script files with every application you develop, you can externalize the functions in a separate JavaScript file and include the functions in the server's global run-time scope using __includeFile().

fileName

A String of the pathname of the JavaScript file to evaluate.

Example 1:

// Sample JavaScript file function checkCreator( userId ) {    var pi = getProcessInstance();    var u = pi.getCreatorUser();    // If the process instance creator matches the    // userId, return true, else false.    if( userId == u.getUserId() )          return true;    else          return false; }

Example 2

// Sample includeList.js file var myIncludePath = "d:\\tmp"; var includePath = __getIncludePath() + ';' + myIncludePath; __setIncludePath( includePath ); __includeFile( "myFunctions.js" );

mapTo

mapTo(fieldName)

Used only from a custom activity as a means of mapping values from the output hashtable back to the process instance. The fieldName parameter specifies the name of a data element in the process instance. This data element receives the value of the current output parameter. When the custom activity's perform() call is complete, the server iterates through the hashtable, one element at a time, and attempts to map the element's value to a field in the process instance. Returns true if data mapping succeeds. Returns false if a problem has occurred.

fieldName

A String of the name of a data element in the process instance.

Example:

mapTo( "customerName" );

mount

mount(jndiName)

Looks up and creates an instance of a stateless session bean, or EJB, found under the given JNDI name. If no bean exists under this name, a javax.naming.NamingException is thrown. Process Manager handles this exception by moving the process instance into the designated Exception Manager node. If the EJB can be found under the given JNDI name, you create an instance of it by calling the create() method on the returned home interface of the bean. This function call is equivalent to the ejbLookup(jndiName).create() function call.

jndiName

A String of the JNDI name of the EJB to "mount."

Example:
var creditServer = mount("Netscape/CreditCardServer");

setConnector

setConnector(connKey, connObject)

Adds a connector object (such as a database connection) indexed by key to the list of connector objects that can be used by scripts.

connKey	A String of the key used to retrieve the associated object (through getConnector()).
connObject	Object stored and associated with the specified key.

JavaScript objects saved inside the Connector , such as those created using var obj = new Object ( ), are converted into Java objects based on the mapping table below before being stored in the connector

JavaScript Data Type	Converted Java Data Type
string	java.lang.String
number	java.lang.Double
boolean	java.lang.Boolean
date	java.util.Date
array	java.lang.Object[]
object	java.util.Hashtable
function	java.lang.String (decompiled source)
script	java.lang.String (decompiled source)
java.lang.Object (wrapped)	java.lang.Object (unwrapped)
java.lang.Object	java.lang.Object (pass-through)

Example:

function initialisationScript( ) { var c = new Packages.com.acme.DBConnection(); setConnector( "dbConnector", c ); return true; } // This DB connection can now be used in any script. var c = getConnector( "dbConnector" );

__setIncludePath

__setIncludePath (includePath)

Allows the user to specify the path the server uses to search for JavaScript source files. The path is a delimited list of absolute directory path names. The delimiter depends upon the system:

• : (a colon) for UNIX

• ; (a semicolon) for Windows

Searches start from the first directory and proceed to the last directory until the file is located. The directory installDir/resources/server/js (where installDir is where Process Manager is installed on the server machine) is included in the search path by default. However, once you set your own path using this function, the current search path is overwritten. Thus, calls to __setIncludePath should specify the entire search path by appending the new search directory to the current search path.

includePath

A String of the search path the server uses to locate JavaScript source files.

Example:

var includePath = __getIncludePath(); includePath += ';' + "d:\\tmp"; // Set the search path. Note how the variable includePath also // specifies the existing search path. // Every call to __setIncludePath // overwrites the previous search path. __setIncludePath( includePath );

setRedirectionURL

setRedirectionURL(stringURL)

Redirects the participant's browser to the specified location in stringURL.

Invoke this method from a completion script so that when the activity has completed, the user immediately sees another HTML page such as a form rather than the standard activity completion dialog box.

The setRedirectionURL() method is typically used for multiple-screen data entry where the same person is required to enter data across several screens of user activities. The process subsequently becomes a wizard-like forms entry screen.

stringURL

A String of a valid URL.

Example:

function scriptComplete( ) {    // Redirect to the Netscape Home Page    setRedirectionURL( "http://home.netscape.com" );    // Alternatively, this causes the next work item in the same    // process instance to be displayed after    // the user clicks an action button    setRedirectionURL( url_OnDisplayProcessInstance() );    // Don't forget to return true;    // this is still a completion script    return true; }

url_OnDisplayHistory

url_OnDisplayHistory()

Returns a string containing the URL that points to the history list for the current process instance. This function is usually used in conjunction with setRedirectionURL() to redirect a user to the history page of the current process instance.

Example:

function scriptComplete( ) { // Redirect to the History Page of this process instance setRedirectionURL( url_OnDisplayHistory() ); // Don't forget to return true; // this is still a completion script return true; }

url_OnDisplayProcessInstance

url_OnDisplayProcessInstance()

Returns a string containing the URL that points the current process instance. This function is usually used in conjuction with setRedirectionURL() to redirect a user to the current process instance.

Example:

function scriptComplete( ) { // Redirect to the current process instance setRedirectionURL( url_OnDisplayProcessInstance() ); // Don't forget to return true; // this is still a completion script return true; }

url_OnDisplayWorklist

url_OnDisplayWorklist()

url_OnDisplayWorklist()

Returns a string containing the URL that points to the user's work list. This function is usually used in conjuction with setRedirectionURL() to redirect a user to their work list.

Example:

function scriptComplete( ) { // Redirect to the user to their work list setRedirectionURL( url_OnDisplayWorklist() ); // Don't forget to return true; // this is still a completion script return true; }

url_OnListApplications

url_OnListApplications()

Returns a string containing the URL listing applications installed on the Process Manager cluster. This function is usually used in conjunction with setRedirectionURL() to redirect a user to the list of applications installed on the cluster.

Example:

function scriptComplete( ) { // Redirect to the list of applications on this cluster setRedirectionURL( url_OnListApplications() ); // Don't forget to return true; // this is still a completion script return true; }

url_OnListEntryNodes

url_OnListEntryNodes()

Returns a string containing the URL that points to the list of entry points in the current application. This function is usually used in conjunction with setRedirectionURL() to redirect a user to the list of entry points in the current application.

Example:

function scriptComplete( ) { // Redirect to the list of entry points of the current application setRedirectionURL( url_OnListEntryNodes() ); // Don't forget to return true; // this is still a completion script return true; }

Alphabetical Summary of JavaScript Methods and Functions

---

The following table lists the JavaScript methods and functions available in Process Manager:

JavaScript Method or Function	Where Used in Process Manager
__getIncludePath	global function
__includeFile	global function
__setIncludePath	global function
addRoleAssignee	workItem
addUser	corporateDirectory
addUserAssignee	workItem
assignees	workItem
checkParallelApproval	predefined script
copy	contentStore
defaultNotificationHeader	predefined script
defaultNotificationSubject	predefined script
deleteUserByCN	corporateDirectory
deleteUserByDN	corporateDirectory
deleteUserById	corporateDirectory
download	contentStore
ejbLookup	global function
emailById	predefined script
emailOfAssignees	predefined script
emailOfCreator	predefined script
emailOfRole	predefined script
evaluateTemplate	global function
exists	contentStore
expire	workItem
expireIn	global function
extend	workItem
getAction	workItem
getApplicationName	global function
getApplicationPath	global function
getApplicationPrettyName	global function
getBaseForFileName	global function
getBaseURL	global function
getConclusion	global function
getConnector	global function
getContent	contentStore
getContentStore ()	global function
getCorporateDirectory	global function
getCreationDate	processInstance
getCreationDate	workItem
getCreatorUser	processInstance
getCreatorUserId	global function
getCurrentActivityCN	workItem
getData	processInstance
getEntityKey	processInstance
getEntryNodeName	processInstance
getException	contentStore
getExitNodeName()	processInstance
getExpirationDate	workItem
getInstanceId ()	processInstance
getJndiNamingContext	processInstance
getPriority	global function
getProcessInstance	processInstance
getRoleUser	contentStore
getRootURL	contentStore
getSize	contentStore
getStatus	contentStore
getSubProcessInstance	global function
getTitle	processInstance
getUserByCN	corporateDirectory
getUserByDN	corporateDirectory
getUserById	corporateDirectory
getUserId	user
getVersion	contentStore
getWorkItem	global function
hasExpired	workItem
initialize	contentStore
isException	contentStore
isStateActive	workItem
isStateRunning	workItem
isStateSuspended	workItem
list	contentStore
logErrorMsg	global function
logHistoryMsg	global function
logInfoMsg	global function
logSecurityMsg	global function
mapTo	global function
mkdir	contentStore
modifyUserByCN	corporateDirectory
modifyUserByDN	corporateDirectory
modifyUserById	corporateDirectory
mount	global function
move	contentStore
moveTo	workItem
randomToGroup	predefined script
remove	contentStore
removeAssignees	workItem
resume	workItem
rmdir	contentStore
setConnector	global function
setData	processInstance
setEntityKey	global function
setErrorMsg	global function
setExpirationDate	workItem
setPriority	processInstance
setRedirectionURL	global function
setRoleById	processInstance
setTitle	processInstance
store	contentStore
suspend	workItem
toCreator	predefined script
toGroup	predefined script
toManagerOf	predefined script
toManagerOfCreator	predefined script
toManagerOfRole	predefined script
toParallelApproval	predefined script
toUserById	predefined script
toUserFromField	predefined script
upload	contentStore