metastorm bpm® release 7 - · pdf filecontents metastorm bpm release 7.5 may 2007 page iii...

Metastorm BPM® Release 7.5

Scripting Developer Guide May 2007

Metastorm Inc. email: [email protected]

http://www.metastorm.com

mailto:[email protected]�

http://www.metastorm.com/�

Metastorm BPM Release 7.5

Page ii May 2007 © Metastorm Inc., 2007

Copyrights and Trademarks

© 1996-2007 Metastorm Inc. All Rights Reserved.

Copyright Notice

Metastorm, Metastorm BPM, e-Work, Process Pod and Enterprise Process Advantage are registered trademarks of Metastorm.

Microsoft®, Outlook®, SQL Server™, Windows®, Active Directory®, Visual Basic®, JScript®, SharePoint® and BizTalk® are either registered trademarks or trademarks of Microsoft Corporation in the United States and/or other countries.

Adobe® is a registered trademark of Adobe Systems, Inc. Netscape® is a registered trademark of Netscape Communications Corporation. Other trademarks are the property of their respective owners.

Disclaimer

Every effort has been made to ensure the accuracy of the features and techniques presented in this publication. However, Metastorm accepts no responsibility, and offers no warranty whether expressed or implied, for the accuracy of this publication. No part of this publication may be reproduced, stored in a retrieval system, or transmitted, in any form or by any means, electronic, mechanical, recording, or otherwise, without the express written permission of Metastorm, Inc. The information in this document is subject to change without notice.

Metastorm Inc. email: [email protected]

http://www.metastorm.com

mailto:[email protected]�

http://www.metastorm.com/�

Contents

Metastorm BPM Release 7.5 May 2007 Page iii

Metastorm BPM Release 7.5 Scripting Developer Guide Table of Contents

1 Introduction: What is Scripting?....................................................................................................... 1 1.1 Supported Scripting Languages .................................................................................................................... 1 1.2 Getting Further Information .......................................................................................................................... 2

2 How to Write Scripts........................................................................................................................... 3 2.1 Script Types.................................................................................................................................................... 3

2.1.1 Server-side Scripting Capabilities..................................................................................................... 4 2.1.2 Client-side Scripting Capabilities...................................................................................................... 4 2.1.3 Running Scripts in the Metastorm Windows Clients....................................................................... 4

2.2 Script Creation ............................................................................................................................................... 4 3 Server-side Scripting.......................................................................................................................... 5

3.1 Calling a Server-side Script through the Integration Wizard....................................................................... 5 3.2 Calling a Server-side Script through the Formula Editor............................................................................. 5 3.3 Features Used in Server-Side Scripting – VBScript and JScript................................................................. 5

3.3.1 ework Object...................................................................................................................................... 5 3.3.2 Metastorm Variables and Functions ................................................................................................. 6 3.3.3 CreateObject Function....................................................................................................................... 7 3.3.4 Evaluate function ............................................................................................................................... 7

3.4 Metastorm Features Used in Server-Side Scripting – JScript .NET............................................................ 8 3.4.1 Writing the script ............................................................................................................................... 8 3.4.2 Running the script............................................................................................................................12

3.5 Script Limitations for Asynchronous Execution ........................................................................................13 4 Client-side Scripting ......................................................................................................................... 14

4.1 Calling a Client-side Script through the Integration Wizard......................................................................14 4.2 Calling a Client-side Script through the Formula Editor ...........................................................................14 4.3 Metastorm Features Used in Client-Side Scripting....................................................................................14

4.3.1 eworkGetField & eworkSetField ....................................................................................................14 4.3.2 Grid Functions..................................................................................................................................19 4.3.3 ShowSubmit and ShowCancel Functions....................................................................................... 20 4.3.4 OnSubmit and OnCancel Functions ...............................................................................................20

5 Sample 1: Client Scripting .............................................................................................................. 22 5.1 Introduction ..................................................................................................................................................22 5.2 Requirements ...............................................................................................................................................23 5.3 Where the Sample Files are Located...........................................................................................................23

6 Sample 2: Server Scripting VB6 (COM and Looping) ................................................................. 24 6.1 Introduction ..................................................................................................................................................24 6.2 Requirements ...............................................................................................................................................24 6.3 Where the Sample Files are Located...........................................................................................................25

7 Sample 3: Server Scripting JScript .NET ...................................................................................... 26 7.1 Introduction ..................................................................................................................................................26 7.2 Requirements ...............................................................................................................................................26 7.3 Where the Sample Files are Located...........................................................................................................27

Appendix A – SyncProcessData and AsyncProcessData ................................................................. 28


Page iv May 2007 © Metastorm Inc., 2007

SyncProcessData ..................................................................................................................................................28 AsyncProcessData................................................................................................................................................34

Metastorm BPM Release 7.5 May 2007 Page 1

Metastorm BPM Release 7.5 Scripting Developer Guide

1 INTRODUCTION: WHAT IS SCRIPTING?

Scripting allows process designers to implement new functionality into Metastorm procedures, using the scripting language of their choice. For example, out-of-the-box Metastorm BPM allows a user to perform a mail-merge using Microsoft Word. If the process designer wants to do a mail-merge using WordPerfect, then they could write a script that drives WordPerfect.

Scripting allows process designers to add or extend Metastorm BPM functionality in the following ways:

• Access and modify folder and other variables (on the Process Engine machine)

• Make calls to Metastorm functions (on the Process Engine machine)

• Access and modify field values (on the Client machine)

• Integrate with third-party applications (on the Engine or Client machines).

1.1 Supported Scripting Languages

Metastorm BPM operates with the following scripting languages:

• VBScript

• JScript®

• JScript .NET


Page 2 May 2007 © Metastorm Inc., 2007

The Script Editor feature in the Metastorm Designer provides color syntax highlighting for these languages.

1.2 Getting Further Information

This manual does not cover the syntax of the supported scripting languages; VBScript, JScript and JScript .NET. For detailed information and tutorials on these scripting languages, go to the URLs listed in the following table:

Scripting Language Reference Where to find it

VBScript Language Reference http://msdn.microsoft.com/scripting/vbScript JScript Language Reference http://msdn.microsoft.com/scripting/JScript JScript .NET Language Reference http://msdn.microsoft.com/library/default.asp?url=/library/en-

us/jscript7/html/jsoriJScript.asp

Table 1: Getting further information

In order to download and install the online scripting language manuals, you will need the latest version of Microsoft HTML Help, which can be downloaded from the Microsoft website.

http://msdn.microsoft.com/scripting/vbScript�

http://msdn.microsoft.com/scripting/JScript�

http://msdn.microsoft.com/library/default.asp?url=/library/en-us/jscript7/html/jsoriJScript.asp�

http://msdn.microsoft.com/library/default.asp?url=/library/en-us/jscript7/html/jsoriJScript.asp�

Scripting Developer Guide


2 HOW TO WRITE SCRIPTS

Three Designer features are used for scripting in Metastorm BPM. These are the:

• Script Editor. This allows you to attach a script to a form or a map. It provides syntax highlighting for VBScript, JScript and JScript .NET, and has links to their functionality. An external text editor may be used instead.

• Integration Wizard. This allows you to call scripts from process events, by choosing options from the wizard.

• Formula Editor. This allows you to call scripts from process events, by typing the calls into the editor.

2.1 Script Types

There are two types of scripts for Metastorm BPM:

• Server-side scripts are scripts executed on the computer on which the Engine is running. These scripts may be attached to a map in the Scripts dialog, and must be called using the Metastorm functions %Script, %ScriptEval, and %ScriptAsync. These functions will be explained in more detail in the Server-side Scripting section.

• Client-side scripts are scripts executed on the computer on which the client is running. These scripts may be attached to a form in the Scripts dialog, and are called in association with specific events through the Client Extensions property of a field.

JScript .NET is supported only for server-side scripting.

You can prepare the syntax to call either type of script using the Integration Wizard or the Formula Editor.



2.1.1 Server-side Scripting Capabilities

On the server side, scripting allows:

• Access to and modification of all context variables, subject to what is normally permitted within a Metastorm formula (for example, changing a folder’s creation time is not allowed). (Modification of context variables is available only for synchronous script calls).

• Calling functions (from synchronous scripts only).

• Synchronous and asynchronous script execution. This means that you can call a script and have Metastorm BPM wait until the script completes execution, or you can call the script without waiting for it to complete execution.

• Return of a result from script execution (available for synchronous script calls only)

• Calling a script that you have written using the Script Editor and associated with a map or form using the Scripts dialog, or calling a script that resides in a file on the Process Engine computer.

2.1.2 Client-side Scripting Capabilities

Client-side scripting allows Metastorm clients to interact with other applications via scripts written in JScript or VBScript. Functions called in client-side scripts are synchronous, and may return a value.

The following events are provided to trigger a script:

• Clicking a button

• Entering a field

• Exiting a field

• Loading a form

• Exiting a cell in a grid

• Submitting a form

• Canceling a form These are accessed via the Integration Wizard in the Designer.

2.1.3 Running Scripts in the Metastorm Windows Clients

For details of the timeout setting when running scripts in the Metastorm Windows clients, refer to the 'Scripting' section of the Designer User Manual.

2.2 Script Creation

For details of script creation, refer to the 'Scripting' section of the Designer User Manual.



3 SERVER-SIDE SCRIPTING

Server-side scripts are scripts executed on the machine running the Process Engine. These scripts can be attached to a map or can be global and therefore available to all maps. You can attach server-side script calls to actions and stages. You can attach these scripts to form and field events, such as when an action or stage completes, when a form is loaded, or when a field value changes.

3.1 Calling a Server-side Script through the Integration Wizard

For details of calling a server-side script through the Integration Wizard, refer to the 'Scripting' section of the Designer User Manual.

3.2 Calling a Server-side Script through the Formula Editor

For details of calling a server-side script through the Formula Editor, refer to the 'Scripting' section of the Designer User Manual.

3.3 Features Used in Server-Side Scripting – VBScript and JScript

The following apply to scripting in VBScript and JScript.

JScript is case sensitive.

3.3.1 ework Object

Metastorm BPM allows access to its context variables and functions from within a server-side script. It is possible to:

• Get and set the values of system and custom variables



• Call standard functions from within the script. Variables and functions are made available via the ework object.

In the ework object, the following naming hierarchy is used:

ework |__ Action |__ Form |__ Session |__ System |__ User |__ Procedure |__ Field

To reference any of these variables or functions, you must place ework in front of the name. The ework reference establishes that what follows refers to data or functions provided by Metastorm BPM.

3.3.2 Metastorm Variables and Functions

The following table shows examples of standard Metastorm variables and functions and their use in VBScript:

Normal Metastorm Custom Variable

Visual Basic Scripting Equivalent

%FolderID ework.FolderID

%Session.UserName ework.Session.UserName

%Notes[0] ework.Notes(0)

%ToDoList( %FolderId ) ework.ToDoList( ework.FolderId )

%Email( %recipientsTo, %recipientsCC, %Subject, "Test email – please disregard")

ework.Email ework.recipientsTo, ework.recipientsCC, ework.Subject, "Test email – please disregard "

Table 2:Metastorm Custom Variables and VB Scripting Equivalents

As long as the script uses the standard ework prefix, it can refer to any of the variables and functions that can normally be referred to in a procedure.

For a full list of standard Metastorm functions and variables, refer to the Designer User Manual.

To assign a value to a check box, the value must be –1 to represent TRUE or 0 to represent FALSE. For example to set a checkbox to be selected (TRUE), the following JScript syntax would be used:

ework.CheckBoxName = -1;



3.3.3 CreateObject Function

If your chosen scripting language does not offer COM object creation, you can use a Metastorm function CreateObject to create COM objects:

Object ework.CreateObject( class [, serverName] )

This function is used to create COM automation objects. The arguments passed are described in the following table:

Argument Description

Class A string containing a reference to the class to create. Can be in the form of: a) ProgId (for example, Word.Basic) or b) Class id (ClsId) (for example,

{000209FE-0000-0000-C000-000000000046})

ServerName A string that specifies the name of the computer on which to create the object. This argument can be omitted or consist of an empty string in order to specify creating the object on the same machine.

Return value An object that is used to return the newly created automation object to caller.

Table 3: CreateObject Arguments

The following is an example using CreateObject in VBScript:

Dim XL XL = ework.CreateObject( “Excel.Application”, “CorporateServer” ) ’ ’ Now use the XL object

3.3.4 Evaluate function

You can use the ework.Evaluate function to return the value of a Metastorm expression (normally entered in the Designer) from within a script. For example, the following function returns the equivalent of ework.folderID:

function EvalFolderID EvalFolderID = ework.Evaluate("%FolderID") end function



3.4 Metastorm Features Used in Server-Side Scripting – JScript .NET

The following apply to scripting in JScript .NET.

Process designers can add server-side scripts written in JScript .NET to processes. In these scripts, the process designer has access to the full .NET SDK.

JScript .NET scripts are added to a process in the same way as those written in JScript or VBScript. However, there are a few differences in the way they can be used. These differences are described below.

JScript .NET is case sensitive.

A sample script is provided in this section.

3.4.1 Writing the script

When writing a server-side script in JScript .NET, the following points must be taken into account.

Entry points

Scripts must contain valid entry points that are used when scripts are executed using %Script, %ScriptEval or %ScriptAsync calls. An entry point is a function with a certain signature.

The signature for a synchronous script is:

public static function <entry_point_name>(ework:SyncProcessData, args: Object[]):Object

The signature for an asynchronous script is:

public static function <entry_point_name>(ework:AsyncProcessData, args: Object[]):Object

The ework parameter

Scripts written in JScript and VBScript have access to a global ework object, which allows the process designer to access folder data, system data and Metastorm functions. When scripting with JScript .NET this access is provided by the ework parameter. This object can be passed around within script functions.

Unlike the VBScript/JScript ework object, the JScript .NET ework parameter is not a global object.

For information on the interfaces of the objects used by the ework parameter (SyncProcessData and AsyncProcessData), refer to Appendix A.



The args parameter

When calling a script using a %Script, %ScriptEval or %ScriptAsync function, the process designer can provide any number of additional arguments. When the entry point is executed, these arguments are packaged in to an object array and passed in as the args parameter. The first argument is held in args[0], the second in args[1] etc. Since args is defined as an object array, the length property can be used to determine how many arguments were passed in.

The Metastorm (ework) object

All scripts must import the library eWork.Engine.ScriptObject, which contains the definition for the SyncProcessData and AsyncProcessData objects. This library is provided with the Metastorm BPM installation.

Custom variables

To access a Metastorm custom variable in a JScript .NET script, use the following syntax:

ework.CustomVariable(<variable name>)

To set a custom variable in a JScript .NET script, use the following syntax:

ework.CustomVariable(<variable name>,<value>)

Message and Notes

To access a folder’s message in a JScript .NET script, use the following syntax:

ework.Message(<index>)

To access folder notes in a JScript .NET script, use the following syntax:

ework.Notes(<index>)

Field value

To access the value of a field on a form, use the following syntax:

ework.Field.Value(<field name>)

Currency variables

Although all custom variables are returned as objects, they are initially mapped to appropriate types. For example, memos and text fields are mapped to strings, integers are mapped to integers, reals are mapped to reals etc. However, currency variables are created as decimals as .NET does not have a currency type. When assigning variables, the Engine will also implicitly convert any decimals to currencies to avoid conversion to reals.



Deadline

The JScript .NET ework objects are strongly typed; i.e. FolderName returns a string, Priority returns an integer and Deadline returns a date. However, until Deadline is assigned it has no value, and a DateTime value in .NET cannot represent a non-date. Therefore if a script attempts to access the Deadline variable before it has been assigned, the system will generate an exception indicating the attempt to read an uninitialized variable.

Date-Time custom variables

The JScript .NET ework object does not strongly type custom variables. Since there is no representation for a non-date in .NET, the ework object in this case will return an empty string (until the date has a value assigned to it).

The JScript .NET ework object ensures that a date custom variable returns an object containing a DateTime object. If this object is concatenated to a string, the format will be different to the value stored in the database.

You should do one of the following:

• Convert the object to a string, for example ework.CustomVariable( "Date1" ).ToString();

• Cast the object to a DateTime variable, for example var a:DateTime = DateTime( ework.CustomVariable( "Date1" ) );

Returning Long values

The data type Long in .NET is a 64 bit integer. There is no way for Metastorm BPM to handle this as a return value. If, when using a %ScriptEval function, a script returns a Long, the value will be converted to a .NET integer. It is recommended that you do not create scripts that return Long values, as this could result in loss of data.

Round function

The Round function's first parameter can be either a decimal value (currency) or a double value (real number).

This value will be included as an element in the args object. Therefore you must cast this value to the relevant type before calling Round in JScript.NET, otherwise an exception will be returned.

In the following example, args[0] is the value and args[1] is the number of decimal places. The result of %Round is assigned to the custom variable, %Round_Result

var dec1 : decimal = decimal(args[0]);

ework.CustomVariable("Round_Result", ework.Round(dec1,args[1]));



%MapName

To retrieve the value of the folder variable %MapName in a JScript .NET script, use ework.ProcessName.

Recursive script calls

Calling JScript .NET scripts from within JScript .NET code using the %Script or %ScriptEval function is not supported.

Sample script

The following script shows the minimum requirements for a Metastorm JScript .NET script. The Designer will create this template when a new script is created.

import System;

import eWork.Engine.ScriptObject; // Required for

// SyncProcessData and

// AsyncProcessData

// add other imports here

package SamplePackage

{

public class SampleClass

{

// Sync entry point:

// SamplePackage.SampleClass.SampleSyncEntryPoint

public function SampleSyncEntryPoint( ework:SyncProcessData, args:Object[]) : Object

{

ework.Subject = “Hello World”;

return true;

}

// Async entry point:

// SamplePackage.SampleClass.SampleAsyncEntryPoint

public class SampleAsyncEntryPoint( ework:AsyncProcessData, args:Object[]) :Object

{

// do async work (all ework data is read-only)

return true;



}

}

}

3.4.2 Running the script

In order to use a JScript .NET script successfully, the following points must be taken into account.

Procedure versioning

Unlike existing script technologies that interpret the scripts each time they are executed, JScript .NET compiles the scripts the first time a new version of the script is used. (Each time a procedure is published, the script is treated as a new version even if it has not changed). In order for the Engine to determine whether a script needs to be recompiled, procedure versioning must be switched on when the procedure is published in the Designer.

Linking to assemblies

Linking to existing assemblies

When compiling a JScript .NET script, the Engine uses a facility called auto referencing. If the Engine encounters an import statement that does not relate to a standard .NET library, it will attempt to locate a DLL of this name in the executing directory.

The standard Metastorm BPM installation creates a directory called dotnetbin in the <Install Dir>\Metastorm BPM\Engine directory.

For example, to use a DLL called mycompany.common.mylibrary.dll, place the file in the dotnetbin directory, and add the following statement to the script:

import mycompany.common.mylibrary

To validate a JScript.NET script from within the Designer Script Editor which calls a third party DLL, the DLL should be copied into the <Install Dir>\Metastorm\Designer\dotnetbin directory.

Linking to assemblies in the Global Assembly Cache

The standard Metastorm BPM installation creates a directory called dotnetlib in the <Install Dir>\Metastorm BPM\Engine directory.

To link to an assembly in the Global Assembly Cache (GAC) at runtime, a copy of the DLL must exist in this directory. This allows the Engine to compile the script that uses the library. However, at run-time, it will bind to the version of the DLL that is stored in the GAC.

Precompilation on start-up



Depending on its complexity, a JScript .NET script can take a long time to compile. To avoid performance issues, it is possible to set up the Engine to compile all currently available scripts on start-up.

To precompile scripts update the following registry setting:

HKEY_LOCAL_MACHINE\Software\Metastorm\e-work\Engine\JScriptPrecompileLevel

Set the value to:

0, for no compilation on start-up

1, to compile map assemblies on start-up

2, to compile procedure assemblies on start-up

4, to compile map and procedure assemblies on start-up.

You may set this registry setting to more than one of the above by combining the values. For example, if the value is set to 7, map assemblies, procedure assemblies and map and procedure assemblies will be compiled on start up.

3.5 Script Limitations for Asynchronous Execution

It should be noted that the following limitations apply if script execution is asynchronous:

• The script has no access to Metastorm functions.

• Variable access is restricted to: Read-only access to folder variables (all variables from the eFolder table plus custom

variables defined in the procedure) Read-only access to ework.Action.Name



4 CLIENT-SIDE SCRIPTING

Client-side scripting allows Metastorm clients to interact with other applications via scripts. Functions called in client-side scripts are synchronous, and may return a value.

For general details of client-side scripting, refer to the 'Scripting' section of the Designer User Manual.

4.1 Calling a Client-side Script through the Integration Wizard

For details of calling a client-side script through the Integration Wizard, refer to the 'Scripting' section of the Designer User Manual.

4.2 Calling a Client-side Script through the Formula Editor

For details of calling a client-side script through the Formula Editor, refer to the 'Scripting' section of the Designer User Manual.

4.3 Metastorm Features Used in Client-Side Scripting

4.3.1 eworkGetField & eworkSetField

To provide access to Metastorm field values, there are two methods for client scripting: eworkGetField, and eworkSetField.

function eworkGetField(FieldName : string, Attribute : string) : string; procedure eworkSetField(FieldName : string, Attribute :

string, Value : string);



These methods provide access to field values and can be called from either JScript or VBScript. When using eworkSetField, the attribute parameter is currently ignored, but will provide access to other field attributes in the future.

For more information about these and other functions available to client scripts, refer to the Client Components Developer Guide section entitled ‘IForm Interface.

Limitations

Client-side scripts have no access to Metastorm functions.

The eworkSetField and eworkGetField client-side scripting methods cannot be used with Grid or Clip form objects, due to the nature of these objects.

Client-side scripts cannot be called from read-only fields in the Web client.

eworkSetField Syntax

The following table illustrates the appropriate eworkSetField syntax (in JScript and VBScript) for each of the Metastorm interactive form elements listed:

Field Script syntax

Check Field

JScript: function SetCheck() { eworkSetField("Check1", "", "True"); }

Acceptable values are: True, False

VBScript: Sub SetCheck eworkSetField "Check1", "", “True” End Sub

Acceptable values are: True, False

Currency Field

JScript: function SetCurrency() { eworkSetField("Currency1", "", "12.34"); }

VBScript Sub SetCurrency eworkSetField "Currency1", "", "43.21" End Sub

Date/Time Field

JScript: function SetDateTime() { eworkSetField("DateTime1", "", "1967-07-07T01:01:01"); }

VBScript: Sub SetDateTime eworkSetField "DateTime1", "", "1971-11-17T01:01:01" End Sub

Drop-down Field

JScript: function SetDropdown() { eworkSetField("Dropdown1", "", "Option2"); }



Field Script syntax

VBScript: Sub SetDropdown eworkSetField "Dropdown1", "", "Option3" End Sub

List Field

JScript: function SetList() { eworkSetField("List1", "", "Option2,Option3"); }

VBScript: Sub SetList eworkSetField "List1", "", "Option1,Option2" End Sub

Memo Field

JScript: function SetMemo() { eworkSetField("Memo1", "", "Sample text"); }

VBScript: Sub SetMemo eworkSetField "Memo1", "", "Sample text" End Sub

Number Field

JScript: function SetNumber() { eworkSetField("Number1", "", "1234"); }

VBScript: Sub SetNumber eworkSetField "Number1", "", "4321" End Sub

Radio Group Field

JScript: function SetRadio() { eworkSetField("Radiogroup1", "", "Option2"); }

VBScript: Sub SetRadio eworkSetField "Radiogroup1", "", "Option3" End Sub

Signature Field

JScript: function SetSignature() { eworkSetField("Signature1", "", "Sample text"); }

VBScript: Sub SetSignature eworkSetField "Signature1", "", "Sample text"

End Sub

Text Field

JScript: function SetText() { eworkSetField("Text1", "", "Sample text"); }



Field Script syntax

VBScript: Sub SetTextField eworkSetField "Text1", "", "Sample text" End Sub

Table 4: eworkSetField Syntax Examples

eworkGetField Syntax

The following table illustrates the appropriate eworkGetField syntax (in JScript and VBScript) for each of the Metastorm form objects listed:

Field Script syntax

Check Field

JScript: function GetCheck() { var tempCheck; tempCheck = eworkGetField("Check1",""); }

VBScript: Sub GetCheck()

dim tempCheck tempCheck = eworkGetField("Check1","")

End Sub

Currency Field

JScript: function GetCurrency() { var tempCur; tempCur = eworkGetField("Currency1",""); }

VBScript: Sub GetCurrency

dim tempCur tempCur = eworkGetField("Currency1","") End Sub

Date/Time Field

JScript: function GetDateTime() { var tempDate; tempDate = eworkGetField("DateTime1",""); }

VBScript: Sub GetDateTime

dim tempDate tempDate = eworkGetField("DateTime1","")

End Sub

Drop-down Field

JScript: function GetDropdown() { var tempDD; tempDD = eworkGetField("Dropdown1",""); }

VBScript: Sub GetDropdown

dim tempDD tempDD = eworkGetField("Dropdown1","")

End Sub

List Field



Field Script syntax

JScript: function GetList() { var tempList; tempList = eworkGetField("List1",""); }

VBScript: Sub GetList dim tempList tempList = eworkGetField("List1","") End Sub

Memo Field

JScript: function GetMemo() { var tempMemo; tempMemo = eworkGetField("Memo1",""); }

VBScript: Sub GetMemo

dim tempMemo tempMemo = eworkGetField("Memo1","") End Sub

Number Field

JScript: function GetNumber() { var tempNum; tempNum = eworkGetField("Number1",""); }

VBScript: Sub GetNumber

dim tempNumber tempNumber = eworkGetField("Number1","") End Sub

Radio Group Field

JScript: function GetRadio() { var tempRG; tempRG = eworkGetField("Radio1",""); }

VBScript: Sub GetRadio

dim tempRadio tempRadio = eworkGetField("Radio1","") End Sub

Signature Field

JScript: function GetSignature() { var tempSig; tempSig = eworkGetField("Signature1",""); }

VBScript: Sub GetSignature dim tempSignature tempSignature = eworkGetField("Signature1","") End Sub

Status Field



Field Script syntax

JScript: function GetStatusValue() { var tempStatusValue; tempStatusValue = eworkGetField("Status1",""); }

function GetStatus() { var tempStatus; tempStatus = eworkGetField("Status1","Status"); }

VBScript: Sub GetStatusValue

dim tempStatusValue tempStatusValue = eworkGetField("Status1","") End Sub

Sub GetStatus

dim tempStatus tempStatus = eworkGetField("Status1","Status") End Sub

Text Field

JScript: function GetText() { var tempText; tempText = eworkGetField("Text1",""); }

VBScript: Sub GetText

dim tempText tempText = eworkGetField("Text1","") End Sub

Table 5: eworkGetField Syntax Examples

4.3.2 Grid Functions

The following client side script functions are provided specially for grids:

function eworkGetCurrentRow(Grid : string) : number; function eworkGetCurrentCol(Grid : string) : number; function eworkGetRowCount(Grid : string) : number; function eworkGetCell(Grid : string; Col : number; Row: number) : string; function eworkSetCell(Grid : string; Col : number; Row: number; Value : string);

eworkGetCurrentRow

This method returns the index of the selected row in the underlying dataset. In the cell exit event handler, it returns the row that has just been left, rather than the one being entered. For compatibility with Version 5 client-side functions, this index is zero-based.

In previous releases calls to eWorkGetCell (using the result from eWorkGetCurrentRow) were not returning correct data. To resolve this problem,



eWorkGetCurrentRow has been changed in Release 7.5 to return an index based on the whole dataset rather than the current displayed page.

eworkGetCurrentCol

This method returns the index of the currently selected column. In the cell exit event handler, it returns the column that has just been left, rather than the one being entered. For compatibility with Version 5 client-side functions, this index is zero-based.

eworkGetRowCount

This method returns the number of rows in the grid, excluding the header.

eworkGetCell

This method returns the string value of the cell specified by the zero-based Col and Row.

eworkSetCell

This method sets the value of the cell specified by the zero-based Col and Row.

4.3.3 ShowSubmit and ShowCancel Functions

The following client-side script functions are provided for showing and hiding the Submit and Cancel buttons on a form:

procedure eworkShowSubmit(Visible : boolean); procedure eworkShowCancel(Visible : boolean);

eworkShowSubmit

This function provides the ability to show or hide the Submit button. For example, the Submit button could be hidden until valid data has been entered in the form.

eworkShowCancel

This function provides the ability to show or hide the Cancel button.

4.3.4 OnSubmit and OnCancel Functions

You can specify a script function to be called when a form's OnSubmit or OnCancel event handler is used. To do this:

1. In the Designer, use the Scripts dialog to create a script function.

2. Select the form to which you want to assign the script function.



3. From the form's Client Extensions field, start the Integration Wizard.

4. From the Form extensions category, select the Run a submit script or Run a cancel script item and click the Next button.

5. Complete the required information for the OnSubmit or OnCancel function.

An OnSubmit function must return a Boolean value. If the script returns:

• False, the submit action fails.

• True, the submit action succeeds. This enables a process designer to submit only forms that validate.

An OnCancel script cannot prevent the form being cancelled.



5 SAMPLE 1: CLIENT SCRIPTING

5.1 Introduction

The Metastorm Software Developer’s Kit (SDK) contains a procedure (Client Script.xep) that demonstrates the client scripting capabilities of Metastorm BPM. More specifically, it demonstrates:

• The following events supported by client scripting: Entering a field Exiting a field Submitting a form Cancelling a form Running a script when a form is submitted Running a script when a form is cancelled Running a script when a form is loaded

• The ability to get and set field values by using these two methods: eworkGetField eworkSetField

The procedure also contains the following sample scripts:

• Example JScript to add the values of two numeric fields, Number1 and Number2, and assign the result to a third numeric field, Number3. eworkSetField("Number3", "", parseInt(eworkGetField("Number1", "")) +

ParseInt(eworkGetField("Number2","")));

• Example VBScript to iterate through all the fields on the form and display each one’s name and value. for FieldLoop = 0 to FieldCount-1



MsgBox("Name = " + Field(FieldLoop).FieldName + " Value = " + Field(FieldLoop).Value)

Next

• Example JScript to launch Outlook, create an email and set the email's To address to a field specified in the form. var Outlook = new ActiveXObject("Outlook.Application"); var item = Outlook.CreateItem(0); item.To = eworkGetField("ToText", ""); item.Display(false);

• Example JScript to set a numeric field to a random value. eworkSetField("Random", "", Math.random());

5.2 Requirements

You must publish the procedure in order for this sample to work.

5.3 Where the Sample Files are Located

The following is the default path created during installation:

C:\Program Files\Metastorm\SDK\Samples\Client Scripting



6 SAMPLE 2: SERVER SCRIPTING VB6 (COM AND LOOPING)

6.1 Introduction

The Software Developer’s Kit (SDK) contains an example of server scripting in use. It demonstrates how VBScript can be used to create and use a COM object. In this case, the object provides a set of methods that allow the Windows Registry to be read and written to.

The following sample functions are included:

• A simple function that returns the registry value of a supplied key.

• A more complex function that will build up a tree of information that can be displayed in a Metastorm memo field. It iterates through a given registry key, building up a list of all values and sub-keys found.

This sample is intended to give a basic introduction to the possibilities of scripting. It includes the use of COM components and other programming approaches now available within Metastorm BPM, such as the use of recursion and loops (for and while) within a function.

Once the procedure has been published and the REG.DLL file has been registered (see requirements below), a new blank form will become available (RegScripting). When you open a new copy, you will see the Engine version number and the registry tree displayed automatically in the appropriate text fields.

6.2 Requirements

For this example to work, you must first:

• Register the supplied .DLL file, REG.DLL on the Engine computer. You must have administrator rights to register the DLL correctly.



• Publish the scripting procedure. A blank form called RegScripting will become available; this will show the information returned from example calls to the functions described.



C:\Program Files\Metastorm\SDK\Samples\Server Scripting



7 SAMPLE 3: SERVER SCRIPTING JSCRIPT .NET

7.1 Introduction

The Software Developer’s Kit (SDK) contains an example of JScript .NET server side scripting in use. It demonstrates how JScript .NET can be used to invoke a class provided by a .NET assembly. The object queries the currently executing application domain and provides information on the properties of the domain and a list of the assemblies that are currently loaded.

A simple sample function is provided, which uses the AppDomainInfo.dll assembly to obtain information on the current app domain. The function includes full exception handling and shows how an argument can be passed via the args object.

The sample shows how an assembly can be imported and invoked, along with some basic usage of the ework and args objects provided by all JScript .NET invocation points.

7.2 Requirements

To use the sample:

1. Copy the AppDomainInfo.dll file to the following location: [Metastorm location]\ Engine\dotnetbin

2. Publish the dotnetServerScripting.xep procedure. A new blank form, Display App Domain Info, is now available.

3. Open the Display App Domain Info form. You see the properties of the App Domain in which the Engine's JScript .NET scripts are currently executing.





C:\Program Files\Metastorm\SDK\Samples\dotnetServerScript



APPENDIX A – SYNCPROCESSDATA AND ASYNCPROCESSDATA

Scripts written in JScript .NET have access to a Metastorm variable, which is a SyncProcessData or an AsyncProcessData object. This variable allows the process designer to access folder data, system data and Metastorm functions.

This appendix outlines the interfaces of:

• SyncProcessData

• AsyncProcessData The variables and functions described in this appendix match, in most cases, the variables and functions of the global ework object used in VBScript and JScript scripts.

For detailed information on the variables and functions of the global e-Work object, refer to the Designer User Manual.

SyncProcessData

The SyncProcessData object is used in synchronous entry points. It allows read/write access to folder and system variables (where this is allowed by the standard specification) and the e-Work functions.

The full interface supported by SyncProcessData and its sub-objects is listed below.

public class SyncProcessData

{ // Folder Variable Access public int ActionCount // read-only property public bool Archived // read-only property



public string Category // read-write property public DateTime CreationTime // read-only property public DateTime Deadline // read-write property public DateTime EntryTime // read-only property public string FolderID // read-only property public string FolderName // read-write property public string Message( int index ) public string Notes( int index ) public string Originator // read-only property public string Parent // read-write property public int Priority // read-write property public string ProcessName // read-only property public string ServerName // read-only property public string StageName // read-only property public string Subject // read-write property public DateTime Updated // read-only property // Custom Variable Access // get function public object CustomVariable( string name ) // set function public void CustomVariable( string name, object obj ) // Additional Request/System data objects public SyncActionObject Action public SyncFieldObject Field public SyncProcedureObject Procedure public SyncSessionObject Session public SyncSystemObject System public SyncUserObject User // Functions public double Abs( object val ) public int Asc( object val ) public string CaptureAttachment( string folderid,

string filename, string attachment )

public string Chr( object val ) public string Concatenate( params object[] args ) public short Count( string text, string delimiter ) public object CreateObject( string name ) public object CreateObject( string name, string computer ) public bool Delete( string name ) public bool DeleteAttachment( string folderid, string filename) public string Dir( string path ) public double Duration( DateTime fromTime, DateTime toTime ) public double Duration( DateTime fromTime, DateTime toTime,

string units ) public bool Email( string to, string cc, string subject,



string message ) public bool Email( string to, string cc, string subject,

string message, string attachments ) public bool Email( string to, string cc, string subject,

string message, string attachments, string reply )

public string EmailAddress( string users ) public string EmailAddress( string users, string delimiter ) public string Empty() public object Evaluate( string formula ) public bool ExecProc( string name, params object[] args ) public bool ExecSQL( string sql ) public bool ExecSQL( string sql, string dsn ) public bool Execute( string name, params object[] args ) public bool ExecuteRule( string rule, params object[] args ) public int Find( string substring, string source ) public int Find( string substring, string source,

int caseSensitive ) public int Find( string substring, string source,

int caseSensitive, int start ) public int FindEntry( string source, string item ) public int FindEntry( string source, string item,

string delimiter ) public string FormatCurrency( object val ) public string FormatCurrency( object val, string lcid ) public string FormatCurrency( object val, string lcid,

int fdigits, bool ldigits, int grouping, string dsep, string tsep, int negorder, int posorder, string symbol )

public string FormatNumber( double number, int precision ) public string FormatNumber( double number, int precision,

int width ) public string FormatNumber( double number, int precision,

int width, string flag ) public string FormatTime( DateTime time, string format ) public bool GetAttachment( string folderid, string filename,

string pathname ) public string GetData( string connection, string table,

string rows, string field ) public string GetData( string connection, string table,

string rows, string field, string fieldsep )

public string GetData( string connection, string table, string rows, string field, string fieldsep, string rowsep )

public string GetEntry( string source, int item ) public string GetEntry( string source, int item,

string delimiter ) public string GetFolder( string table, string where,

string column ) public string GetText( string filename )



public string LDAPSearch( string url, string search, string username, string password, string filter, string attributes )

public string LDAPSearch( string url, string search, string username, string password, string filter, string attributes, int scope )

public int Length( string source ) public string Linefeed() public DateTime MakeDate( int offset, string units,

string direction, DateTime start ) public string Manager( string user, string role ) public string Manager( string user, string role, string alt ) public object Max( params object[] args ) public object Min( params object[] args ) public DateTime Months( DateTime start, int offset ) public DateTime Never() public string NewAttachment( string folderid, string filename,

string path ) public string Newline() public string Open( string filename ) public bool Print( string name, string folderid ) public bool Print( string name, string folderid,

string printer ) public bool Print( string name, string folderid,

string printer, string output ) public bool RaiseFlag( string flagname, string flagfolder,

params object[] args ) public string ReadAttachment( string folderid, string filename) public bool RegisterInQueue( string name, string system,

string host, string queue, string user, string process, string clientType, string map, string stage, string action, string param )

public bool RegisterOutQueue( string name, string system, string queue, string param )

public int Rem( int number, int divisor ) public string RemoveEntry( string source, int index ) public string RemoveEntry( string source, int index,

string delimiter ) public string Replace( string source, string old,

string replacement ) public string Replace( string source, string old,

string replacement, int count ) public decimal Round( decimal val, int places ) public double Round( double val, int places ) public double Round( double val, int places, string round ) public bool Run( string name, string args ) public bool SaveData( string folderid, string filename ) public bool Script( string language, string files,

string procedure, string map,



string script ) public bool Script( string language, string files, string

procedure, string map, string script, params object[] args )

public bool ScriptAsync( string language, string files, string procedure, string map, string script )

public bool ScriptAsync( string language, string files, string procedure, string map, string script, params object[] args )

public object ScriptEval( string language, string files, string procedure, string map, string script )

public object ScriptEval( string language, string files, string procedure, string map, string script, params object[] args )

public string SelectFolder( string table, string where, string column )

public string SelectSQL( string sql ) public string SelectSQL( string sql, string connection ) public string SelectSQL( string sql, string connection,

string fieldDelimiter ) public string SelectSQL( string sql, string connection,

string fieldDelimiter, string rowDelimiter )

public string SelectSQL( string sql, string connection, string fieldDelimiter, string rowDelimiter, bool headers )

public bool SendMQMessage( string name, string message, int priority, int timeToLive )

public bool SendMQMessage( string name, string message, int priority, int timeToLive, string folderid )

public bool SendMQMessageEx( string type, string queue, string message, int priority, int timeToLive, string param )

public string Staff( string user, string role ) public string Staff( string user, string role, string alt ) public string Substring( int start, int length, string source ) public string TodoList( string folderid ) public string WatchList( string folderid ) public DateTime Weekdays( DateTime start, int offset ) public bool WriteText( string contents, string filename ) public bool WriteText( string contents, string filename,

string create ) public bool UnregisterInQueue( string name ) public bool UnregisterOutQueue( string name ) }



RaiseFlag

public bool RaiseFlag( string flagname, string flagfolder, params object[] args )

Data is extracted from the arguments array by calling the ToString() method on each object in the array. You should ensure that when ToString() is called on types passed as an argument, the resulting string contains data in the format required by the process which owns the flag being raised. This requires overriding the default Object.ToString() behavior, or formatting a suitable string in the client code before passing the data as an argument.

public class SyncActionObject { public string Name // read-only property public string Notes // read-write property public string StartsStage // read-only property } public class SyncFieldObject { public string Value( string name ) } public class SyncProcedureObject { public string Name // read-only property public string Version // read-only property } public class SyncSessionObject : SyncBaseObject { public string FlagData( int column ) public string FlagName // read-only property public string FlagRaiser // read-only property } public class SyncSystemObject : SyncBaseObject { public string Name // read-only property public string Roles // read-only property public DateTime Time // read-only property public string Users // read-only property } public class SyncUserObject : SyncBaseObject { public string Error // read-write property public string Form // read-only property public string Input // read-only property public System.Array InputItem // read-only property public string Name // read-only property



}

AsyncProcessData

The AsyncProcessData object only allows read access to most of the folder and system variables.

The full interface supported by AsyncProcessData is listed below.

public class AsyncProcessData { // Folder Variable Properties public int ActionCount // read-only property public String ActionName // read-only property public bool Archived // read-only property public string Category // read-only property public DateTime CreationTime // read-only property public DateTime Deadline // read-only property public DateTime EntryTime // read-only property public string FolderID // read-only property public string FolderName // read-only property public string Originator // read-only property public string Parent // read-only property public int Priority // read-only property public string ProcessName // read-only property public string ServerName // read-only property public string StageName // read-only property public string Subject // read-only property public DateTime Updated // read-only property // System Objects public AsyncActionObject Action public AsyncProcedureObject Procedure public AsyncUserObject User // Custom variable access public object CustomVariable( string name ) } public class AsyncActionObject { public string Notes // read-only property public string StartsStage // read-only property } public class AsyncProcedureObject : AsyncBaseObject { public string Name // read-only property



public string Version // read-only property } public class AsyncUserObject : AsyncBaseObject { public string Error // read-only property public string Form // read-only property public string Input // read-only property public System.Array InputItem // read-only property public string Name // read-only property }

metastorm bpm® release 7 - · pdf filecontents metastorm bpm release 7.5 may 2007 page iii...

Documents