Administration Guide

Transcription

Metastorm BPM®
Release 7.6
May 2008
Metastorm Inc.
email: inquiries@metastorm.com
http://www.metastorm.com
Metastorm BPM Release 7.6
Copyrights and Trademarks
© 1996-2008 Metastorm Inc. All Rights Reserved.
Copyright Notice

Metastorm®, Metastorm BPM®, e-Work®, Process Pod®, Enterprise Process Advantage®, ProVision®, The
Best Process Wins®, Proforma®, Metastorm Knowledge Exchange™, Metastorm DNA™, Metastorm
Discovery™, STAR™, Insight™, Envision™, and Metastorm Enterprise™ are either registered trademarks or
trademarks of Metastorm in the United States and/or other countries.

Microsoft®, Outlook®, SQL Server™, Windows®, Vista®, 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: inquiries@metastorm.com
http://www.metastorm.com
ii
May 2008
© Metastorm Inc., 2008
Contents
Table of Contents
1
Introduction.......................................................................................................................................... 1
2
Services Manager................................................................................................................................ 2
2.1
Accessing Services Manager......................................................................................................................... 2
2.1.1
Services Manager Window .................................................................................................................. 3
2.1.2
Toolbar buttons ..................................................................................................................................... 3
2.2
Connecting to a Metastorm Database ........................................................................................................... 3
2.3
Working with the Metastorm Database ........................................................................................................ 5
2.3.1
Publish Procedure or Library................................................................................................................ 5
2.3.2
Clear Locks............................................................................................................................................ 5
2.3.3
Folder Lock Timeout ............................................................................................................................ 5
2.3.4
Purge Alerts........................................................................................................................................... 6
2.3.5
Purge Deletion Alerts............................................................................................................................ 6
2.3.6
Diagnostics ............................................................................................................................................ 7
2.3.7
Designer Log......................................................................................................................................... 8
2.3.8
Check Data .......................................................................................................................................... 10
2.4
Libraries........................................................................................................................................................ 11
2.4.1
Libraries Management ........................................................................................................................ 11
2.5
Procedures .................................................................................................................................................... 12
2.5.1
Viewing Procedure Components........................................................................................................ 13
2.5.2
Deleting a Procedure........................................................................................................................... 14
2.5.3
Purging Stages..................................................................................................................................... 15
2.5.4
Resetting Passwords............................................................................................................................ 15
2.5.5
Setting Map Groups ............................................................................................................................ 16
2.5.6
Deleting a Map.................................................................................................................................... 17
2.5.7
Version Control................................................................................................................................... 18
2.5.8
Folder Operations................................................................................................................................ 19
2.5.9
Sub-folders .......................................................................................................................................... 23
2.6
Working with Metastorm Query................................................................................................................. 24
2.7
Working with Metastorm Migrator............................................................................................................. 24
3 Users and Roles ................................................................................................................................ 27
3.1
Role-based Work Management................................................................................................................... 27
3.2
Identifying the Users and Roles Assignments in Your Organization........................................................ 28
3.2.1
Identifying Users................................................................................................................................. 28
3.2.2
Identifying Role Assignments ............................................................................................................ 29
3.2.3
Defining Roles..................................................................................................................................... 29
3.3
The Users and Roles Utility ........................................................................................................................ 29
3.3.1
Accessing Users and Roles................................................................................................................. 29
3.4
The Users & Roles Window ....................................................................................................................... 30
3.4.1
Users & Roles Menu Options............................................................................................................. 31
3.4.2
Users & Roles Tabs............................................................................................................................. 31
3.5
The Users Tab.............................................................................................................................................. 32
3.5.1
Checking Roles through the Users Tab ............................................................................................. 33
May 2008
iii
3.5.2
Adding Users through the Users Tab................................................................................................. 33
3.5.3
Adding the Current User through the Users Tab............................................................................... 34
3.5.4
Setting User Details through the User Tab ........................................................................................ 34
3.5.5
Viewing a User's Role Assignments through the Users Tab ............................................................ 35
3.5.6
Granting Role Assignments through the Users Tab.......................................................................... 36
3.5.7
Removing/Changing Role Assignments through the Users Tab...................................................... 37
3.5.8
Deleting a User through the Users Tab.............................................................................................. 38
3.6
The Roles Tab .............................................................................................................................................. 39
3.6.1
Checking Roles through the Roles Tab.............................................................................................. 39
3.6.2
Viewing Role Assignments through the Roles Tab........................................................................... 40
3.6.3
Granting a Role to a User or Group of Users through the Roles Tab............................................... 40
3.6.4
Removing a Role from a User or Group of Users through the Roles Tab........................................ 41
3.7
The Attributes Tab ....................................................................................................................................... 41
3.7.1
Defining Standard Attributes through the Attributes Tab ................................................................. 42
3.7.2
Defining Custom Relationships through the Attributes Tab............................................................. 43
3.8
The Staff Tab................................................................................................................................................ 47
3.8.1
Defining Your Organizational Structure through the Staff Tab........................................................ 47
3.8.2
Adding New Users to the Staff Hierarchy through the Staff Tab ..................................................... 49
3.8.3
Deleting Users through the Staff Tab ................................................................................................. 50
3.8.4
Defining Staff Member Details through the Staff Tab ...................................................................... 50
3.9
The Lists Tab................................................................................................................................................ 51
3.9.1
Creating a List of Users with a Specified Role through the Lists Tab.............................................. 52
3.9.2
Adding a List of New Users through the Lists Tab ........................................................................... 53
3.9.3
Adding a List of Users from a File through the Lists Tab................................................................. 54
3.9.4
Granting a Specified Role to a List of Users through the Lists Tab.................................................. 54
3.9.5
Removing a Specified Role from a List of Users through the Lists Tab.......................................... 55
4 System Administrator....................................................................................................................... 56
4.1
Opening System Administrator................................................................................................................... 56
4.2
Metastorm System Administrator Components......................................................................................... 57
4.3
Metastorm BPM........................................................................................................................................... 57
4.3.1
Welcome Tab ...................................................................................................................................... 58
4.3.2
Maintenance Tab................................................................................................................................. 59
4.3.3
Managing Tab ..................................................................................................................................... 60
4.3.4
Tools Tab............................................................................................................................................. 61
4.4
Metastorm Query......................................................................................................................................... 61
4.4.1
Query Toolbar ..................................................................................................................................... 62
4.4.2
Designing Reports............................................................................................................................... 63
4.5
Metastorm Process Engines......................................................................................................................... 64
4.5.1
Metastorm Authentication .................................................................................................................. 66
5 Engine ................................................................................................................................................. 67
5.1
Operating Environment ............................................................................................................................... 67
5.1.1
Starting the Engine.............................................................................................................................. 67
5.1.2
Troubleshooting: Problems Starting the Engine................................................................................ 69
5.1.3
Troubleshooting: Engine Failure........................................................................................................ 71
5.1.4
Reviewing Engine Settings................................................................................................................. 72
5.1.5
Security................................................................................................................................................ 74
5.1.6
Re-registration of the Engine.............................................................................................................. 76
5.1.7
.NET CLR Configuration ................................................................................................................... 79
5.2
Configuring the Engine Service .................................................................................................................. 81
5.2.1
Troubleshooting .................................................................................................................................. 81
5.3
Engine Registry Settings.............................................................................................................................. 82
5.3.1
Script Timeout..................................................................................................................................... 82
iv
May 2008
Contents
5.3.2
JScript Query Timeout........................................................................................................................ 82
5.3.3
Activate CallerID ................................................................................................................................ 82
5.3.4
Query Timeout .................................................................................................................................... 83
5.3.5
Login Timeout..................................................................................................................................... 83
5.3.6
Force Case-insensitive Authentication............................................................................................... 83
5.3.7
Force Case Sensitive Role Evaluation ............................................................................................... 84
5.3.8
Fire When Changed On Submit ........................................................................................................ 84
5.3.9
Disable Static Role Resolution........................................................................................................... 84
5.3.10
Max Simultaneous Async Jobs .......................................................................................................... 85
5.3.11
Install Info............................................................................................................................................ 85
5.3.12
JScript Precompile Level.................................................................................................................... 85
5.3.13
Allow Guest User To Raise Flag........................................................................................................ 86
5.3.14
Microsoft Workflow Timeout ............................................................................................................ 86
5.3.15
Microsoft Workflow Enabled............................................................................................................. 86
5.4
Engine and Invalid XML............................................................................................................................. 87
5.5
Engines and Time Zones ............................................................................................................................. 87
5.6
Database Connections.................................................................................................................................. 88
5.7
Event Manager............................................................................................................................................. 88
5.7.1
Configuring the Event Manager......................................................................................................... 88
5.7.2
Event Manager Registry Settings....................................................................................................... 89
5.8
Alert Generator ............................................................................................................................................ 90
5.8.1
Alert Generator Configuration Columns ........................................................................................... 91
5.8.2
Alert Generator Registry Settings....................................................................................................... 92
5.9
Custom Notification..................................................................................................................................... 93
5.9.1
Custom Notification Example............................................................................................................ 93
6 Rolling Out the Mail Clients............................................................................................................. 94
6.1
Elevated Privileges....................................................................................................................................... 94
6.2
Specifying Install Parameters...................................................................................................................... 95
6.2.1
The /s Argument.................................................................................................................................. 95
6.2.2
The /qn Argument............................................................................................................................... 95
6.2.3
The /qb Argument............................................................................................................................... 95
6.2.4
The /v Argument ................................................................................................................................. 95
7 Administration of Metastorm Clients............................................................................................. 97
7.1
Configuring the List of Available Metastorm Services ............................................................................. 97
7.1.1
Service List Configuration File .......................................................................................................... 98
7.1.2
Configuring HTTP Connection for TP Clients................................................................................106
7.1.3
Load Balancing .................................................................................................................................106
7.2
Clearing the Most Recently Used Forms List ..........................................................................................107
7.3
Setting Client Font Sizes ...........................................................................................................................107
7.4
Troubleshooting the Web Client ...............................................................................................................107
7.4.1
Viewing Error Messages...................................................................................................................107
7.4.2
Windows NT login dialog appears when using web forms ............................................................107
7.4.3
Browser Closes..................................................................................................................................108
7.5
Allowing Multiple Outlook Users from One Installation ........................................................................108
7.6
Setting the Session Time-out Period.........................................................................................................108
7.7
Setting Up Automatic Refresh of Alerts Lists in the Web Client............................................................110
7.8
Configuring Globalization Settings in the Web Client ............................................................................110
7.8.1
Browser Settings Administration Form ...........................................................................................111
7.8.2
Changing Locale settings in Web.config .........................................................................................111
7.8.3
Supporting Browser ‘Preferred Languages’ ....................................................................................112
7.8.4
Setting the Default Language ...........................................................................................................113
May 2008
v
7.9
Administering the Metastorm web parts for SharePoint Server..............................................................113
7.9.1
Introduction .......................................................................................................................................113
7.9.2
Permissions........................................................................................................................................114
7.9.3
Adding Web Parts .............................................................................................................................115
7.9.4
Web Part Global Settings..................................................................................................................118
7.9.5
Setting Default Values for Web Part Properties ..............................................................................118
7.9.6
Setting up Windows Single Sign-On ...............................................................................................118
7.9.7
Advanced UI Customization ............................................................................................................119
7.9.8
Configuring Language and Regional Settings.................................................................................120
7.9.9
Configuring Alerts and Forms Lists.................................................................................................121
7.9.10
Catering for Visually Impaired Users ..............................................................................................122
7.10 Document Management Support (DMS) .................................................................................................123
7.10.1
Opening Microsoft Office Documents using DMS ........................................................................124
7.10.2
Opening a DMS Document and Internet Explorer..........................................................................124
7.11 Custom Lists...............................................................................................................................................125
7.11.1
Custom List Types ............................................................................................................................125
7.11.2
Defining Custom Lists ......................................................................................................................125
7.11.3
Publishing Custom List Admin Procedure ......................................................................................125
7.11.4
Filtering Custom Lists.......................................................................................................................126
7.11.5
User Name Filtering Example for the Flight Sample Procedure ....................................................127
7.11.6
Formatting Custom Lists ..................................................................................................................129
7.11.7
Custom List Restrictions...................................................................................................................130
7.11.8
Metastorm BPM Client for Office and Custom Lists......................................................................130
7.11.9
Configuring the Custom List Web Part............................................................................................131
8 Configuring Open Authentication ................................................................................................ 132
8.1
Chaining SAP Authentication Scripts.......................................................................................................134
8.2
Enabling Public Access .............................................................................................................................136
8.3
Configuring Digital Signatures .................................................................................................................136
9 Configuring Metastorm BPM Parameters ................................................................................... 138
9.1
Registry Settings ........................................................................................................................................138
9.1.1
HKEY_LOCAL_MACHINE..........................................................................................................138
9.1.2
HKEY_CURRENT_USER .............................................................................................................142
9.2
Non Registry Settings................................................................................................................................142
9.2.1
Engine Service...................................................................................................................................142
9.2.2
Metastorm User Groups....................................................................................................................142
9.2.3
Web Client (Web.Config) settings...................................................................................................143
9.2.4
Web Interface Browser Settings.......................................................................................................143
10
Configuring Metastorm Notify Gadget..................................................................................... 144
10.1 Configuring Steps ......................................................................................................................................144
10.2 DefaultSettings.xml ...................................................................................................................................145
10.2.1
Locking a Setting ..............................................................................................................................145
10.2.2
Connection Settings ..........................................................................................................................145
10.2.3
Priority Settings.................................................................................................................................147
10.2.4
Other Settings....................................................................................................................................148
Appendix A - Administrative Procedures ........................................................................................... 151
Publishing an Administrative Procedure................................................................................................................152
Locating the Administrative Procedures ...........................................................................................................152
Using the Administrative Libraries....................................................................................................................152
Notes on the Administrative Procedures................................................................................................................153
Browser Settings.................................................................................................................................................153
Business Activity Monitoring ............................................................................................................................153
vi
May 2008
Contents
Designer Log.......................................................................................................................................................156
eB2B....................................................................................................................................................................156
KPI Dashboards..................................................................................................................................................157
Line of Business Reporting................................................................................................................................158
List Maintenance ................................................................................................................................................159
MQ Administration ............................................................................................................................................159
Purge....................................................................................................................................................................161
Query...................................................................................................................................................................162
Service Monitor ..................................................................................................................................................162
Update Time out .................................................................................................................................................162
User Profiling......................................................................................................................................................162
Appendix B - Web Interface Registry Settings................................................................................... 163
Appendix C – Metastorm Web Parts Settings in Web.Config.......................................................... 164
Appendix D – Custom List Web Part Dataset Definition .................................................................. 166
Appendix E – Metastorm Web Parts Public Properties .................................................................... 170
Service Web Part.....................................................................................................................................................170
To Do / Watch List Web Parts ...............................................................................................................................170
Blank / Admin Forms List Web Part .....................................................................................................................171
Dashboard View Web Part.....................................................................................................................................172
Custom List Web Part.............................................................................................................................................172
May 2008
vii
Metastorm BPM Version Release 7.6
1
INTRODUCTION
This document describes how to use the following Metastorm BPM utilities:
•
Services Manager — Enables Process Administrators to manage folders and procedures;
query the Metastorm database, and upgrade from version 6 to version 7.
•
Users and Roles — Enables Process Administrators to identify users, define their
attributes, and make static role assignments.
The Users and Roles utility is recommended for development and testing environments, or if you
are not working in a directory services environment.
•
System Administrator — Enables System Administrators to perform administrative tasks
such as configuring database connectivity and registering Process Engines.
•
Public Access — makes business processes available to users outside your organization, by
enabling external users to create folders
It also describes how to perform configuration and administrative tasks.
In addition, Appendix A describes the Administrative procedures shipped with Metastorm BPM
that may be used to administer Metastorm BPM.
Metastorm BPM Utilities are installed as part of the Metastorm BPM installation and can be
accessed from Metastorm BPM | Administrative Tools.
May 2008
1
2
SERVICES MANAGER
The Services Manager enables those responsible for process administration to manage Metastorm
services. The Services Manager provides the following functions:
•
View database diagnostic information, such as the Designer log.
•
Manage procedures (and their components, such as forms and maps) and libraries.
•
Query the database.
•
Migrate a Metastorm database to a new version.
2.1
Accessing Services Manager
To open the Service Manager, navigate to Metastorm BPM | Administrative Tools | Services
Manager. The Services Manager utility is displayed.
Figure 1:Services Manager Display
2
May 2008
2.1.1
Services Manager Window
The Console Tree of the Services Manager main window contains the following components:
•
Services Manager– contains the items associated with the various services available
through the Services Manager:

2.1.2
Database– enables you to connect to a Metastorm database and:

view its diagnostic information in the Designer Log

administer its libraries and procedures

Query— enables you to run SQL statements against the database.

Migrator—upgrades version 6.x databases to version 7 databases, by updating the
database schema and content.
Toolbar buttons
The Toolbar has a number of buttons that perform specific actions. The content of the Toolbar
varies according the function selected in the Navigation Pane. The Toolbar buttons include the
following:
Button
Name
Function
Connect
Opens a connection dialog to a database.
Publish
Procedure
Enables you to select one or more procedure or library (.xep or
.xel) files to publish. The procedures cannot be edited.
Clear Locks
Unlocks any folders that have been locked for longer than a day.
A folder becomes locked when a user is modifying it or
performing an action upon it, such as filling out a form.
This prevents multiple users from editing or modifying
the folder at once.
Folder Lock
Timeout
Enables you to specify the number of seconds after which a
locked folder in the database is automatically unlocked.
Purge Alerts
Purges obsolete alerts from the database.
An alert is considered obsolete if it either has no folder associated
with it or is an uncommitted folder older than one day.
Purge Deletion
Alerts
Deletion alerts are used only by Windows based clients
and are therefore not used by users accessing
Metastorm BPM through a web browser.
Opens the Purge Deletion Alerts dialog.
Table 1: Database Action
2.2
Connecting to a Metastorm Database
To connect to the database:
May 2008
3
1.
Select Metastorm Database service in the navigation pane.
2.
Either click the Connect button
on the toolbar or right-click the Metastorm Database
service in the navigation pane’s console tree and select Connect from the drop down menu.

The Connect dialog is displayed:
Figure 2: Connect Dialog
3.
In the Connect dialog select the data source of the Database you want to administer, enter
your User name and Password for the database.
4.
Click the OK button.
Figure 3: Metastorm Database items
4
May 2008
2.3
Working with the Metastorm Database
After you have connected to a database, and expanded the database item in the console tree
(Figure 3: Metastorm Database items) the following options are available:
•
Diagnostics — provides troubleshooting information from the database. This option is
described in section 2.3.6.
•
Libraries — displays information for libraries in the database. This option is described in
section 2.4.
•
Procedures — displays information for procedures in the database. This option is
described in section 2.5.
The database name is displayed as ‘Metastorm Database’ rather than as the DSN for the database.
Set out below are the functions available to manage the databases.
2.3.1
Publish Procedure or Library
To publish a procedure or library:
1.
Select Metastorm Database.
2.
Click on the Procedure

button;
A Windows browse dialog is displayed.
3.
Browse to the required file for the procedure or library.
4.
Select the file and click the Open button.
2.3.2
Clear Locks
When the database item is selected in the tree or the main pane, clicking the Clear Locks
button unlocks any folders in the procedure that have been locked for more than one day.
2.3.3
Folder Lock Timeout
When the database is selected in the tree or the main pane, clicking the Folder Lock
Timeout button displays the following dialog:
May 2008
5
Figure 4: Folder Lock Timeout Dialog
This dialog enables you to specify the number of minutes after which a locked folder is
automatically released for action by a user other than the user who locked it (it is always available
to the user who locked it). A folder is locked when a user is modifying it or performing an action
upon it, such as filling out a form. This prevents multiple users from editing or modifying a
folder at the same time. If a user attempts to open a folder for an action (by selecting the action
button) and this folder is already locked by another user, the following error message is
displayed:
Folder already locked for <action name> by <username>
If two users, logged in using the same user id, lock the same folder to perform an action then the
second user to submit the folder will get the error message:
Folder not locked.
The Folder Lock Timeout can be used to:
•
Prevent a user from leaving a folder open too long and denying access to others.
•
Prevent a folder from being permanently inaccessible when a network or workstation fails.
•
Prevent a folder remaining inaccessible, when a user’s browser has been closed in the
middle of taking an action without committing the action or canceling it.
2.3.4
Purge Alerts
When the database is selected in the navigation pane or the main pane, clicking the Purge
Alerts button removes obsolete alerts from the database. An alert is obsolete if:
•
It is not associated with a folder; or
•
It is an uncommitted folder older than one day.
2.3.5
Purge Deletion Alerts
Deletion alerts are alerts generated by the Process Engine when a folder needs to be removed
from a user’s To Do or Watch list. The Metastorm Client uses deletion alerts to update the local
alerts list on a user’s workstation. Deletion alerts are not removed from the database unless Purge
Deletion Alerts is selected.
6
Deletion alerts are used only by Windows based clients and are therefore not used by users accessing
Metastorm BPM through a web browser.
May 2008
When the database is selected in the navigation or the main pane, clicking the Purge
Deletion Alerts button displays the following dialog:
Figure 5: Purge Deletion Alerts Dialog
This dialog enables you to select and remove deletion alerts. The drop-down arrows in each
column header enable you to filter the list of displayed alerts.
To:
•
purge a specific Deletion Alert in the list of alerts matching the criteria, Select it in the list
and click the Purge button
•
purge all the listed alerts matching the criteria, click the Purge All button
•
close the Purge Deletion Alerts dialog, click the Close button
•
remove the custom filter, and return to the deletion defaults, click the X button.
2.3.6
Diagnostics
Double-clicking the Diagnostics folder in the Main pane or selecting it in the navigation pane
displays the diagnostic reporting options: Check Data and Designer Log. ( see Figure 6:
Diagnostics).
May 2008
7
Figure 6: Diagnostics
2.3.7
Designer Log
When the Designer Log item is selected in the navigation pane, or is double-clicked in the main
pane, the Designer Log is expanded.
Figure 7: Designer Log Report Options
The following Designer Log categories are available:
•
Failed Logins —failed login attempts to the Process Engine.
•
Procedure Errors –procedure warnings and errors.
To view further details, select Failed Logins or Procedure Errors in the expanded Designer Log
tree or double-click the item in the main pane. If data is found which meets the criteria, it is
displayed in the main pane.
8
May 2008
Figure 8: Procedure Errors Display
Times, in the Designer Log, are displayed in service time, not local time.
When data is displayed in the main pane, it can be refreshed by selecting the report item in the
on the toolbar.
tree and clicking the Refresh button
Purging the Designer Log
When the Designer Log item is selected, a Purge button is displayed, on the toolbar, which can
be used to delete all entries before a specified date. (See Figure 9: Purge Dialog).
1.
Click the Purge button.

The Purge dialog is displayed:
Figure 9: Purge Dialog
2.
The Purge entries before this date checkbox defaults to the one week prior to the current
date. Use the drop-down to change this date, if required.
3.
If the date checkbox is not checked, all entries are purged.
To purge Failed login attempt entries or Procedure error entries, check the appropriate
checkboxes.
May 2008
9
4.
For maintenance purposes, you may want to purge the log on a regular basis, as this is not done
automatically.
2.3.8
Check Data
When the Check Data item is selected, or is double-clicked in the main pane or the navigation
pane, the available Check Data reports are displayed in the main pane.
Figure 10: Check Data reports
The following Check Data reports are available:
•
Alerts without Folders – This displays any alerts for non-existent folders.
•
Child folders without Parents – This displays any child-folders that don’t have a parent
folder.
•
Folders without Stages – This displays any folders that are not at a stage.
•
Orphaned Audit Trails – This displays any events for non-existent folders.
•
Orphaned system actions – This displays any waiting actions for non-existent folders
•
Alerts Not on a To Do List –This displays any folders not currently on a To Do list.
To generate a report, open the Check Data item on the tree and click the required item or doubleclick the item in the main pane. If data is found it is displayed in the main pane. If no matching
data is found, a message is displayed stating that no errors were found.
10
May 2008
When data is displayed in the main pane, it can be refreshed by selecting the item in the tree and
clicking the Refresh button on the toolbar.
2.4
Libraries
Selecting the Libraries item in the tree or double-clicking this item in the main pane displays the
currently available published libraries in the main pane. (see Figure 11: Libraries).
Figure 11: Libraries
To view the details of a specific library, double click on a library in the list to or the navigation
pane.
The library details include:
•
Library Name – The name of the library.
•
Version – The version number of the library.
•
Owner – The owner of the library.
•
Publish Time – The time and date the library was published.
•
Description – Notes added to the library when it was published.
2.4.1
Libraries Management
Libraries can be managed by right clicking on the entry in the navigation pane. A dropdown
menu is displayed with options to modify the status of the library in the database.
May 2008
11
Figure 12: Libraries Management
The dropdown menu gives the following options:
Refresh
The library’s contents display is updated to its current status.
View
Select the display form of the library list in the main pane. This includes large or small icons and
details of attributes, see Figure 11: Libraries above.
Delete a library
When Delete is selected a warning dialog is displayed that requests confirmation before the
library is deleted. Select OK to delete the library.
Export List
Allows the selected library to be exported from the database to another location.
2.5
Procedures
When the Procedures item is selected in the navigation pane, a list of all published procedures is
displayed in the main pane and a Refresh button is displayed on the toolbar.
If the Procedure item is expanded in the navigation pane the list of procedures is also displayed
there.
12
May 2008
Figure 13: Procedure Action Options
Right click on a procedure in the list. A dropdown menu is displayed with the following options:
•
View a list of a published procedure’s components, including its static roles, versions,
forms, variables and stages.
•
Delete a procedure.
•
Purge obsolete stages from a procedure.
•
Reset the password for a procedure.
•
Set map groups.
•
Delete a version of a procedure.
2.5.1
Viewing Procedure Components
To view the components of a published procedure, double-click the item in the main pane, or
click on the item in the expanded list in the navigation pane.
The components of the selected procedure are displayed in the main pane:
May 2008
13
Figure 14: Procedure Components
Details of Administration Form sets are available under the Maps item.
2.5.2
Deleting a Procedure
To delete a procedure:
1.
Select a specific procedure in the navigation or main pane.
2.
Click the Delete button on the toolbar, or select Action | Delete or right-click on the
procedure and select Delete.

A confirmation dialog is displayed with a warning.
Figure 15: Confirm Delete
1
Once you delete a published procedure, it, and all folders associated with it, whether
active or inactive, are deleted from the database. Any forms associated with the deleted
procedure are no longer accessible in the Blank Forms list or Administration Forms list
of the Client.
3.
Click the Yes or No button.
4.
If you click on the Yes button, a warning is displayed that the active folders in the
procedure will be lost. If you continue, the procedure is purged from the database and is no
longer available.
14
May 2008
2.5.3
Purging Stages
You can use the Purge Stages button to remove obsolete stages from a procedure. A stage may
be considered obsolete, for example, when the procedure map has been redesigned and the stage
removed.
Before you purge a stage, you must first ensure that no folders remain in the obsolete stage. If a stage
contains a folder, you cannot purge it.
To verify that no folders remain at a stage, open the Map item and the procedure item to display
its stages.
Figure 16: Map Stages
When the map item is selected, the details pane displays all folders currently being processed.
Stages that contain folders will be displayed on the tree preceded with a plus. Stages that do not
contain folders can be purged.
To purge an obsolete stage that contains no active folders, Select the map on the tree and click the
. If folders are present at the stage, an error message is displayed and the
Purge Stages button
purge action is canceled.
2.5.4
Resetting Passwords
When a procedure is selected on the tree or in the details pane, you can use the Reset Password
button to change a password assigned to the procedure. The password is set in the Designer when
the procedure is published, and prevents a user from publishing over another user’s procedure.
May 2008
15
To reset a password:
1.
Select the required procedure.
2.
Click the Reset Password

button.
The Reset Password dialog is displayed:
Figure 17: Reset Password
3.
Type the New Password.
4.
Type the new password again in the Verification field.
5.
Click on the OK button to apply the reset password.
2.5.5
Setting Map Groups
Maps can be grouped within a procedure, for example, by office or business function, using the
Set Map Groups button. To group a set of maps:
1.
Select the relevant procedure in the tree.

2.
becomes available.
Click the Set Map Groups button. Alternatively, select the Set Map Groups option on the
Action menu or right-click on a procedure and select the Set Map Groups option.

16
The Set Map Groups button
The Set Map Group dialog is displayed:
May 2008
Figure 18: Set Map Group Dialog
3.
To set up the map group, click the Edit button. The Edit dialog is displayed:
Figure 19: Set Map Group Edit Dialog
4.
Enter or select a map Group name.
The & character cannot be used in map group names.
5.
Enter or select the name of a Map that will be added to the group.
6.
Click the OK button. The Set Map Group dialog is re-displayed with the map entered into
the specified group:
Figure 20: Set Map Group with Associated Map
7.
Repeat this process until all maps associated with the group have been entered.
8.
In the Client application, this set of maps is now available for all users who have access to the
group.
2.5.6
Deleting a Map
To delete a map:
May 2008
17
1.
Expand a procedure on the tree;

Its maps are displayed in the main pane.
2.
Select the map you want to delete.
3.
. Alternatively, select the Delete Map option from the Action
Click the Delete button
menu or right-click on the map and select the Delete Map option.
Figure 21: Deleting a Map
4.
If active folders are present, a warning informs you that the active folders associated with
the map will be lost.
5.
Click Cancel to abort the deletion or OK to continue.
6.
If you continue, a Confirm dialog is displayed:
Figure 22: Confirm Map Deletion Dialog
The Confirm dialog is displayed directly after the Delete action is performed if no active folders are
associated with the map.
7.
Click on the Yes button.

2.5.7
18
When a map is deleted, all the folders associated with it, whether active or inactive are
also deleted from the database.
Version Control
May 2008
Several versions of a procedure can be stored in the database. You can use the Delete button to
delete a specific version of a procedure.
1.
Locate the version you want to delete by expanding the Versions item of the procedure:
Figure 23: Version Listing
2.
Select the required version from the main pane.
3.
Click the Delete button. Alternatively, select the Delete Version option from the Action
menu or right-click on the version and select the Delete Version option. The Confirm
dialog is displayed:
Figure 24: Confirm Version Deletion Dialog
4.
Click the Yes button.

2.5.8
The version is deleted.
Folder Operations
Viewing Folders
You can view information about folders at several levels:
•
To view a list of all folders associated with a specific map, expand the procedure item and
select the map in the tree. The list displays the following information for each folder:
May 2008
19

Folder name.

Stage at which the folder is currently located.

Folder ID.

Subject of the folder.
•
To view a list of all folders associated with a specific map stage, expand the map item and
Select the required stage in the tree. The list displays information for each folder at that
stage as defined by the columns set by the user.
•
To view information about a specific folder, expand the relevant stage item and select the
folder. Information categories are displayed in the main pane and a plus sign becomes
available next to the folder.
Figure 25: Folder Details
•
20
Expand the folder and select an information category to view its details. Information
available for each folder includes:

Attachments –any files attached to the folder.

History – an audit trail of events associated with the folder.

Parent –information about the folder’s parent (if one exists).

Child-folders –information about the folder’s children (if any exist).
May 2008

Users – users who see the folder on their To Do or Watch lists.
Updating Folder Details
You can update the following information for a selected folder:
•
Subject.
•
Priority.
•
Category.
To edit these details:
1.
Select the folder you want to edit.
2.
Click the Update Folder button.
A dialog similar to the following is displayed:
Figure 26: Update dialog
3.
Make the required changes to the folder’s Subject, Priority and Category.
4.
Click on the OK button.
Deleting Folders
To delete a folder:
1.
Select a folder in the navigation pane or the main pane.
2.
Click the Delete button, or right click and select Delete from the drop down menu.

A confirm deletion dialog appears:
Figure 27: Confirm Deletion dialog
May 2008
21
3.
Click on Yes to continue the deletion or No to abort the deletion.
Unlocking Folders
To unlock a folder:
1.
Select the folder.
2.
Click the Unlock button
the dropdown menu.
3.
The folder is unlocked.
, or right click on the selected folder and select Unlock from
Assigning Users
To view the users associated with a specific folder:
1.
Expand the folder in the tree.
2.
Select the Users item.
The users are displayed in the main pane.
To add or re-assign users:
1.
Select the folder item.
2.
Click the Assign User button.
3.
An Assign User dialog similar to the following is displayed:
Figure 28: Assign User Dialog
You can assign the folder to, or remove a folder from, a user’s To Do or Watch list.
22
May 2008
You may want to do this in a situation where a user changes jobs; in a new job, they may need to
be assigned to the To Do list, rather than the Watch list. Or you may need to do this for
temporary assignments.
You can move the user’s name to the appropriate lists as follows:
•
Select the user’s name and click the left or right arrow button, as appropriate.
•
Drag and drop the user’s name from one list to another.
The Users tab is also a useful tool for troubleshooting assignment problems.
The List Maintenance administration form can be used to move and copy To Do and Watch list entries
between users.
Clearing Stuck Folders
If a Process Engine server becomes disconnected from the network, there is a possibility that
some rows will remain locked in the Metastorm database e.g. if a timed or flagged event was
being processed at the point of disconnection. This could result in delays in processing timed or
flagged actions even after the server has been restarted because another engine will be unable to
process the folder locked by the failed session.
Eventually, depending on the database server configuration, the inactive sessions belonging to the
engine which failed may time out - which will remove the associated locks and permit processing
to resume.
In some configurations the database server may never kill the inactive session, or the delay may
be unacceptably long, so the locked folders may never restart. For as long as the locks remain, the
Engine attempting to process the action will not be able to process any other timed events. If this
happens, the database sessions belonging to the failed server must be killed by the database
administrator to allow processing to continue.
2.5.9
Sub-folders
You can view information about a parent folder and its children. A parent folder is created by an
original map; a child folder is a sub-folder created by an instance of a sub-procedure map.
Under the Child-Folders item, you see listed sub-folders that are children of the folder displayed
in the details pane. A child folder stores the folder ID of its parent folder in the eParent field of its
record in the eFolder table. This happens automatically when:
•
A folder is created automatically by a sub-procedure stage. The parent folder ID is that of
the folder that caused the sub-map to be initiated.
•
A folder is created by a flag action where the flag raised to trigger the flag action was
raised by another Metastorm procedure.
•
A folder is created when a cloned action is used.
A process designer can also set the parent ID using an assignment operation.
May 2008
23
Under the Parent item, you see information about the currently selected folder’s parent folder.
When the folder does not have a parent, no information is displayed.
2.6
Working with Metastorm Query
Metastorm Query enables the user to query databases. Query is not limited solely to Metastorm
databases – any database can be queried using this tool, provided a DSN has been set up and
authentication information is known.
Refer to Section 4.4 for details on working with the Metastorm Query tool.
2.7
Working with Metastorm Migrator
Migrator upgrades Metastorm databases from one version to another to allow existing procedures
and libraries to be used with the latest version of Metastorm BPM. This section gives an overview
of the Migrator tool; specific requirements for migration of a database for use with the latest
version of Metastorm BPM are given in the Migration Guide.
For further details, refer to the Migration Guide
The migration procedure is as follows:
1.
Make a backup copy of the database to be migrated.

This provides security against loss or corruption of data.
2.
Ensure the Process Engines running against the database are stopped.
3.
Select Migrator in the navigation pane.
4.
Click the Migrate button

.
The database connection dialog appears:
Figure 29 : Database connection dialog
5.
24
Enter the required database User name and Password.
May 2008
6.
Select the DSN for the Metastorm Database.
7.

If the database is not a Version 7 and is capable of migration a warning is displayed to
Backup the database, and ensure the necessary privileges have been granted.
Figure 30: Warning before Migrate action
8.
Click Yes to continue.

Migrator displays operational requirements in the main pane.

Any prerequisites are flagged and information displays define actions required before
migration can continue. In the example shown in Figure 31 a message is displayed to
inform that user that Migration is not required.
Figure 31: Migrator Messages
9.
Run the SQL or Oracle scripts according to the type of database.

10.
The scripts are stored in Metastorm BPM | Engine | Database which contains SQL
Scripts and Oracle Scripts.
For the SQL scripts in SQL Query select the required Database, connect to the database and
select the SQL Server-create.sql script.
May 2008
25
Refer to the Migration Guide for details of Oracle database migration.
11.
12.
Press F5 to execute the script and repeat the process for the eworkprocedures.sql script. The
name of the script to run has the format <x> - Create.SQL where x is “SQL Server” or
“Oracle”.
We recommend you use the sqlcmd tool provided with SQL Server 2005 Express Edition to run the
scripts. Please do not attempt to use the Query administrative tool for this purpose.
When the scripts have been executed:

Migrator publishes all procedures and deletes all temporary files and folders.

Messages are displayed to report publishing of procedures and libraries and removal of
temporary folders, see Figure 32 below.

The final message is Migration complete.
Figure 32 : Migrator Messages
13.
26
The new tables are now populated with data. Your database is ready for use with
Metastorm BPM Version 7.
May 2008
3
USERS AND ROLES
Metastorm BPM uses the concepts of users and roles to control access to the various parts of the
application, and to determine what information users receive from the system.
A user is defined as anyone in an organization who uses the Metastorm system. In most cases,
this includes everyone on the staff roster, and can be expanded to include contract or temporary
workers, suppliers, customers, or business partners, as required.
Roles are a way of grouping people in an organization. Individuals can be grouped by skill,
function, geographical location, or any other criteria relevant to your organization. A user can
have any number of roles, and a role can be assigned to one or many users. Roles are created
during the process design and added to the database when a procedure is published.
In this section, we introduce you to the Users and Roles tool and cover the following topics:
•
Role-based work management.
•
Identifying users and role assignments in your organization.
•
Managing users.
•
Managing roles.
3.1
If you are working in a directory services environment, you can use the Metastorm Directory
Extraction Service to import user information. In this situation, you may not need to use the Users
and Roles tool.
Role-based Work Management
Metastorm BPM is patterned on the concept of role-based work management, which involves
assigning tasks and routing information to a role (such as System Engineer), rather than to a
person (such as John, who is a System Engineer). For the designer, role-based work management
eliminates the need for first-hand knowledge of the names of specific individuals in an
organization and the positions they occupy. For the recipients, role-based work management
May 2008
27
eliminates the need for a response from a specific person, but instead places the responsibility on
the role, regardless of whether it is held by an individual or a group of individuals.
Metastorm BPM offers the following options for user and role management:
•
Users and Roles
A tool provided as part of the Administrative Tools suite for identifying users, defining
their attributes, and making static role assignments.
•
Directory Extraction Service
A set of modules used to extract user-related attribute data from Directory Services and
store this data in the database.
For specific instructions on using the Directory Extraction Service, refer to the Directory
Integration Suite Guide.
When you import user information with the Directory Extraction Service, most roles
defined in procedures are dynamic, based on attributes cached in the database. (Instructions
for creating dynamic roles can be found in the Metastorm Designer User Manual.)
You can also make static role assignments for these users through Users and Roles, if
required.
•
Open Authentication
Allows process designers to create their own custom authentication scripts.
For details on Open Authentication, refer to the Open Authentication Architecture Guide,
which is distributed as part of the Metastorm SDK, available from the Metastorm website.
3.2
Identifying the Users and Roles Assignments in Your
Organization
To identify the roles in your organization, and assign the proper users to these roles, you must
answer the following two questions:
•
What individuals will use the system (in any capacity)?
•
What roles do these individuals occupy in my organization?
3.2.1
Identifying Users
You can create an initial user list based on your organization’s employee list. Depending on your
organization’s needs and organization, the employee list may:
•
Contain individuals who are not participants in workflow procedures (such as a pool of
workers without access to the system, but who answer directly to a supervisor who logs
their production). These employees should be deleted from your preliminary list.
•
Not include any non-employees (such as contract workers or temporary employees) who
may become process participants. These non-employee users should be added to your list.
28
May 2008
If you discover that you need to add or delete a user for any reason, you can return to the Users and
Roles utility and make the necessary modifications to the user list. These changes become effective
immediately.
As you refine your user list, it is a good idea to organize it by workgroups, teams, departments,
etc. This method not only helps ensure that all individuals are accounted for, but it is useful when
you move to the next step, identifying role assignments.
3.2.2
Identifying Role Assignments
Because role-based work management is based on the concept that responsibilities are assigned
based on an individual’s job function—or role—in the organization, the simplest way to make the
proper role assignments is to link users with their job title. This is where having organized your
user list according to your organization divisions becomes helpful.
The list you develop may not reflect all possible role assignments in your organization. You can
define new roles (static or dynamic) as procedures require them. Similarly, you can modify role
assignments as changes in your organization require.
3.2.3
Defining Roles
Roles for procedures are defined in the maps that are built for procedures. For detailed
information on how to define roles, consult the Designer User Manual.
3.3
The Users and Roles Utility
The Users and Roles utility enables you to manage the static roles assigned in your organization.
These roles are defined in the process of designing a procedure map. (For more information on
defining roles, consult the Designer User Manual).
Role management tasks include:
•
Adding and deleting users.
•
Granting a role to a user or group of users.
•
Granting multiple roles to a user.
•
Viewing a user’s roles.
•
Validating role allocations.
•
Viewing the holders of roles.
•
Removing a role from a user or group of users.
•
Removing a user from a role.
3.3.1
Accessing Users and Roles
To access the Users and Roles utility, follow these steps:
May 2008
29
1.
Select the Metastorm BPM | Administrative Tools | Users and Roles.
Figure 33: Users & Roles Login
2.
Enter the User name and Password for the database you selected.
3.
From the Database drop-down list, select the ODBC Data Source Name (DSN) that points
to the database you want to connect to.
The default ODBC data source name is Metastorm.
The Users & Roles window is displayed:
Figure 34: Users & Roles Window
3.4
The Users & Roles Window
The status bar at the bottom of the window displays:
•
30
The number of registered users in the database.
May 2008
•
Mouse-over “tool tip” messages describing the options available to you when your cursor is
over particular portions of the screen.
The primary functionality of the Users and Roles utility is accessed through the following
elements:
•
A menu bar.
•
Tabbed pages.
Each of these elements are discussed in detail below.
3.4.1
Users & Roles Menu Options
The Users & Roles window contains two menu options:
•
•
File which contains the following options:

Reconnect – Accesses the database to update any information that may have been
posted to the database since the Users and Roles utility was launched.

Exit – Closes the Users and Roles utility.
Help, which contains the following options:

Contents & Index – Accesses the Users and Roles Help files.

Metastorm Web Site – Opens a browser and connects to http://www.metastorm.com

About – Displays information about the version of Users & Roles
3.4.2
Users & Roles Tabs
The Users & Roles window contains five tabs:
•
Users
•
Roles
•
Attributes
•
Staff
•
Lists
Each tab enables you to manage user and role information in specific ways. Some tasks, such as
adding users and updating user details, can be performed through more than one tab.
May 2008
31
3.5
The Users Tab
Click on the Users tab on the Users & Roles window. The Users tab is displayed:
Figure 35: Users Tab
The Users tab enables you to perform the following tasks:
•
Add new users.
•
Add the current user (the user logged into the network).
•
Set or modify user details.
•
View a user’s role assignments.
•
Assign roles to a user.
•
Remove or change role assignments.
•
Delete users.
•
Check that all roles have been assigned.
Note that when working with roles on this screen, you can
•
Click to select a single role.
•
Shift + Click to select several adjacent roles.
•
Ctrl + Click to make several non-adjacent selections.
32
May 2008
3.5.1
Checking Roles through the Users Tab
By using the Check Roles button, you can verify that all static roles have been allocated to users.
Check Roles cannot verify dynamic roles because these are evaluated only when a folder is
processed.
1.
On the Users tab, click the Check Roles button.

The Check Roles screen appears:
Figure 36: Check Roles Screen
The result of this check either:
•
Warns you if certain roles do not have users assigned to them (as shown in Figure 36:
Check Roles Screen).
•
Verifies that all roles do have users assigned to them.
3.5.2
Adding Users through the Users Tab
To add users to the database:
1.
Click on the Add button. The Add User screen appears:
Figure 37: Add User
2.
3.
In the User name field, type in the user you want to add.
You should not start or end the User name with spaces, or include ampersands.
Click OK.
May 2008
33

4.
You can make role assignments for this user and update their user details, as required.
Repeat steps 1 to 3 until you have added all the users you require.
3.5.3
Adding the Current User through the Users Tab
The current user is the user that is currently logged on to the machine where the Users and Roles
utility is running. Typically, the current user’s name is the network login ID. You cannot use the
Add Current User button if you are not logged into a network.
To add the current user to the list of registered users:
1.
From the Users tab, click on the Add Current User button.

2.
The user is added to the drop-down list of registered users, and the number of
registered users is updated in the status bar.
Make role assignments and update the user’s details, as required.
3.5.4
Setting User Details through the User Tab
The Details button enables you to set up various details for users to support email and directory
services, as well as assigning managers and specifying passwords.
If you use the Directory Extraction Service to import user information, the user details are
automatically placed in these fields. However, if you are not using a directory, this information can
be entered manually.
1.
From the Users tab, select the user for whom you are entering details from the drop-down
list, then click on the Details button.
2.
The User Details dialog for the user you have selected is displayed.
Figure 38: User Detail Dialog
Enter the user's email address in the Address field. This value can then be referenced by a
process designer to send email to the user.
34
May 2008
3.
Select the Deliver alerts via e-mail check box if this user should be sent every alert via the
email system,.
4.
Enter the Distinguished Name and Directory tree where this user’s data can be found.

5.
Select the name of the user to whom this user reports, from the drop-down list in the User
reports to field.
Any structure you set up here is reflected in the staff hierarchy on the Staff tab. If you make changes
on the Staff tab, those changes are reflected here as well.
6.
These fields support integration with external directory services.
Click on the Password button >> and enter a Password for users to log into the Metastorm
Client.
When running against an Oracle database, extended (accented) latin 1 and latin 2 characters are not
supported in passwords.
Figure 39: User Details - Passwords
7.
Re-enter the password in the Confirm password field.
8.
9.
Metastorm BPM encrypts and stores the password for the user.
You can modify a user’s details at any time. Changes made to a user’s details take effect as soon as
the User Details dialog is closed.
3.5.5
Viewing a User's Role Assignments through the Users Tab
You may want to see which roles a user holds in the organization:
•
From the Users tab, select the user name you want to review from the drop-down list.
May 2008
35
•
A list of the roles assigned to that user (if any) in the Roles held field, is displayed.
Figure 40: Viewing Role Assignments
3.5.6
Granting Role Assignments through the Users Tab
Users often have responsibilities for a number of applications. In Metastorm BPM, it is possible
to recognize this fact, and grant single or multiple roles to an individual user. To grant multiple
roles:
1.
2.
From the Users tab:

Select an existing user from the Select a User drop-down list; or

To add a new user, click on the Add button and type the name in.
From the Roles available list select the role (or roles) to be granted to this user.

3.
Click on the < button to move the selected role or roles to the Roles held field.
4.
36
The roles you have defined through previously published procedures are displayed in
alphabetical order in the Roles available field, see Figure 40: Viewing Role
Assignments above.
If the < < button is used, it moves all the roles listed in the Roles available field to the Roles
held field. You can also drag & drop roles from one field to another.
Repeat steps 1 to 3 for any other users to whom you want to assign roles.
May 2008
3.5.7
Removing/Changing Role Assignments through the Users Tab
As users move within your organization, their roles may change. To remove a user’s role
assignments in the database, and make new assignments:
1.
From the Users tab, select the user from the drop-down list.
2.
The roles held by this user are displayed in alphabetical order in the Roles held field.
3.
From the Roles held field, select the role (or roles) to be removed from this user.
4.
Click on the > button to move the selected role or roles to the Roles available field.
If the >> button is used, it moves all the roles listed in the Roles held field to the Roles
available field. You can also drag & drop roles from one field to another.
Figure 41: Removing or Changing Role Assignments
5.
From the Roles available field, select any new roles to be assigned to this user, then click
on the < button to move these roles to the Roles held field.
You can modify a user’s role assignments at any time. Changes made to a user’s role
assignments take effect immediately. Folders that were on this user’s To Do or Watch lists
based on the previous role assignment remain, but all subsequent folders are based on the new
role.
If you remove a role assignment from the only user who held it, without making a new
assignment for that role, any procedure that uses that role is affected.
When a role assignment is made, be aware that the assignment is not retrospective. For
example, only folders arriving at the stage this role has responsibility for after the role
May 2008
37
assignment has been made appear on the user’s To Do or Watch list. Folders that were
previously at that stage do not appear on the user’s To Do or Watch list.
An Administrator may use the List Maintenance sample procedure to add or move the To Do
and Watch list items of one user to another if necessary.
3.5.8
Deleting a User through the Users Tab
You can delete that user from the list of registered users. To do so you must first remove any role
assignments for that user. To delete a user:
1.
From the Users tab, select the user to be deleted from the drop-down list.
2.
Select all the roles held by that user.
3.
Click on the >> button to remove the role assignments from this user.

If you do not remove the roles first, you see the following message when you click on
the Delete button:
Figure 42: Remove Role Assignments Warning
4.
Click on the Delete button.
5.
The user is removed from the drop-down list of registered users, and the display of the
number of registered users in the status bar is updated.
Be aware that if you remove the only user who held a particular role, without making a new
assignment for that role, any procedure that uses that role is affected. In addition, items (alerts)
that were on this user’s To Do or Watch lists must be reassigned to another role through the
Services Manager.
38
May 2008
3.6
The Roles Tab
Click on the Roles tab on the Users & Roles window.
The Roles tab is displayed:
Figure 43: Roles Tab
The Roles tab enables you to perform the following tasks:
•
View current role assignments.
•
Assign a role to a user or group of users.
•
Remove or change role assignments.
•
Check that all roles have been assigned.
All users are given the role “Everybody” by default. This role cannot be added, deleted, or removed
from a user, and is not displayed in the list of available roles.
3.6.1
Checking Roles through the Roles Tab
By using the Check Roles button, you can verify that:
•
All static roles have been allocated to users.
•
All static roles are used in published procedures.
When you select the Check Roles button, all user and static role assignments are evaluated, and
the database is searched to verify that all static roles listed in Users and Roles are used in
May 2008
39
published procedures. Any static roles that are not used or which do not have users assigned are
listed in the Check Roles dialog box for you to review.
Refer to page 33 for further details.
3.6.2
Viewing Role Assignments through the Roles Tab
You can easily see your organization’s current static role assignments.
From the Roles tab, select the role you want to review from the drop-down list.
A list of those users assigned to that role (if any) in the Users with role field is displayed; see
Figure 43: Roles Tab above.
3.6.3
Granting a Role to a User or Group of Users through the Roles
Tab
If you have a group of users that share a common role, it may be more convenient to make a
single role assignment to the entire group rather than assign the role to each user individually. To
grant a role to a group of users:
1.
From the Roles tab, choose the required role from the Select a role drop-down list.

2.
Any users with the selected role are shown in the Users with role field. All other users
are shown in the Users without role field.
Select as many users as necessary for this role.
Figure 44: Granting a Role
40
May 2008
3.
Click the << button to move the users to the selected role.
3.6.4
Removing a Role from a User or Group of Users through the
Roles Tab
When one or more users are no longer allocated to a particular role, you can remove that role
from those users. To remove the role from a user or group of users:
1.
From the Roles tab, select the role to be removed from the Select a role drop-down list.
2.
Select as many users as necessary from the Users with role list.
Figure 45: Removing a Role
3.
3.7
Click the >> button to remove the selected users from the list.
The Attributes Tab
You can use the Users and Roles utility to build tables of attributes that can be used when
creating dynamic roles in procedures. The values of these attributes can be accessed in the
Process Designer using the User attribute item in the Users and roles category of the Integration
Wizard.
In a Microsoft Active Directory environment, you can use the Active Directory property page to
populate the attributes table.
Details on building dynamic roles and using the Integration Wizard can be found in the Designer
User Manual.
May 2008
41
To display the Attributes screen, click on the Attributes tab on the Users & Roles window. The
following screen is displayed:
Figure 46: Attributes Tab
The Attributes tab enables you to perform the following tasks:
•
Define standard attributes for a user or group of users.
•
Create custom relationships.
•
Delete a custom relationship.
3.7.1
Defining Standard Attributes through the Attributes Tab
1.
From the Attributes tab, select Attributes from the drop-down list.
2.
Click in the User column. A drop-down list of registered users appears. Alternatively, you
can type the first letter of the user name; the first user name that begins with that letter
displays. If you continue to type the name, the program searches for names starting with the
first two characters, then three, and so on as you type in the name.
3.
Enter the name of the attribute in the Attribute column. For example, this could be
Region, Department, or Project.
4.
Enter the value for that attribute in the Value column.
42
May 2008
Figure 47: Attributes Tab
5.
Save the current row by tabbing out of the row. Adding a blank row for the next entry
automatically saves the current row before enabling you to proceed.
6.
To add another user to the table, place the cursor in any column and hit the Add row
button. A new line is inserted into the table.
If you begin to complete a row and then decide you do not want to add it, press Escape to
discard your changes.
7.
Add user attribute details for this user. Repeat for as many users as necessary.
8.
As user and attribute details are added, the lines are sorted and displayed in alphanumeric
order by username. To sort the table by an attribute or value, click on the required column
heading.
You must save the current row before changing the sorting option, or the row is deleted.
Similarly, if you select another table to work with, or move to another tab of Users & Roles
without saving the current row, the row is deleted from the list.
3.7.2
Defining Custom Relationships through the Attributes Tab
You can set up relationship tables through the Attributes tab.
1.
On the Attributes tab, click on the Add button.

The Add Relationship dialog for the new custom relationship is displayed.
May 2008
43
Figure 48: Add Relationship
2.
In the Name field, enter the name of the custom relationship and click on the OK button.

The Define Relationship dialog appears:
Figure 49: Define Relationship
3.
Enter the names for two or more related attributes in the dialog box. After each attribute,
start a new line. When you are finished, click on the OK button.

4.
44
The attribute names you enter into this dialog box form the column headings in the
custom relationship table you are building.
Attribute names cannot contain spaces; only letters, digits, and underscores. For example, an
attribute name such as “Product Specialty” would have to be entered as “ProductSpecialty” or
“Product_Specialty.”
The Attributes tab is updated to display the new custom relationship table you have
defined.
May 2008
Figure 50: Attributes Tab – Relationship defined
5.
Place your cursor in the User column and click once.

A drop-down list of all registered users appears.
6.
Select a name from the list.
7.
Use the Tab or arrow keys to move between attribute columns.
8.
Click on the Add row button to add another user to your relationship table.
9.
Repeat until you have added all the users you require.
Delete a row
To delete a row:
1.
Place your cursor anywhere in the row and select the Delete row button.

A confirmation dialog appears.
May 2008
45
Figure 51: Confirm Row Deletion
2.
Click on the Yes button if you are sure you want to delete the selected row.
Process designers can use the data in relationship tables to build dynamic roles. Dynamic roles
can be broad or specific.
Figure 52: Sample Relationship
For example, using the relationship table illustrated in Figure 52: Sample Relationship above, you
could build the specific role of "Personnel manager" by making a query to this table:
%Users where Department='Personnel' and Item='Manager'
The only user who matches this role definition is Paul Pascal.
As another example, using the relationship table illustrated above, you could build the broad role
of "Customer Service Representatives" by making a query to this table of:
%Users where Department='Sales' and Item='CSR'
In this case, the users Sam Smith and Bertie Blauer match this role definition.
46
May 2008
3.8
The Staff Tab
Metastorm BPM makes it easy for you to reproduce the structure of your organization, whether
you are specifying it from scratch or making modifications.
To display the Staff tab, click on its tab extension on the Users & Roles window.
The Staff tab is displayed.
Figure 53: Staff Tab
The Staff tab enables you to perform the following tasks:
•
Define your organizational structure.
•
Add new users to the staff hierarchy.
•
Modify the organizational structure.
•
Define staff member details.
The Staff tab can handle approximately 2,000 names. Once this limit has been exceeded, you must use
the Reports to field in the User Details dialog.
3.8.1
Defining Your Organizational Structure through the Staff Tab
To define your organizational structure through the Staff tab:
1.
Click on the Staff tab on the main Users & Roles window.

The Staff hierarchy is displayed.
May 2008
47
Figure 54: Defining Organizational Structure on Staff Tab
2.
Your user list is initially displayed in a single-level structure, with no pre-defined
hierarchy, unless you specified a relationship through the Details option (User reports to
field) when you added the user to the database. Alternatively it has been defined in your
directory and cached using the Directory Integration Suite.
3.
Move users into the proper hierarchy using one of the following methods:
a) Select a user from the list, then drag and drop them onto their new manager; or
b) Select a user from the list, and then click on the Details button.

The Details Dialog appears.
Figure 55: User Details
4.
On the Details dialog, select the user’s manager from the User reports to drop-down list.
Click the OK button to return to Staff tab.
5.
Click on the Move button:
48
May 2008

The Move Staff… dialog is displayed.
Figure 56: Move Staff… Dialog
6.
Select the person that the user should report to from the drop down field then click on the
OK button.
7.
The organizational structure is built in a collapsible “tree” structure:
Figure 57: Staff Tree
3.8.2
1.
You can contract each level to show the manager only by clicking on the minus sign (-) before
the manager’s name. To expand the hierarchy, click on the plus sign (+) before a person's
name.
Adding New Users to the Staff Hierarchy through the Staff Tab
To add further users to the staff hierarchy, select the user who is to be the new user's
manager, then click on the Add button.

The Add Staff dialog is displayed:
Figure 58: Add Staff
May 2008
49
2.
Enter the name of the new user, click on the OK button.

Metastorm BPM registers the new user, and updates the displayed staff hierarchy to
show that the new user has been added to the manager’s group.
3.
To add a user at a different level, click on the new manager, then click on the Add button
and enter the user name.
4.
Continue building the structure by selecting managers and adding their staff.
3.8.3
New users added in this method are also added to the database. Be sure to make the necessary
role assignments for each of these users before exiting Users and Roles.
Deleting Users through the Staff Tab
The staff hierarchy can be modified through the Staff tab at any time, as required.
Select an individual’s name, then click on the Delete button.
Individuals deleted from the staff hierarchy are also deleted from the list of registered users.
3.8.4
Defining Staff Member Details through the Staff Tab
As you add individuals to your organizational structure, you may want to add their user details at
the same time.
For further details, refer to section 3.5.4.
1.
The User details dialog is displayed for the user you have selected.
Figure 59: User Details
2.
Enter the user's email address in the Address field.

3.
50
You should always enter a fully qualified email address of the form user@domain.
This value can be referenced by a procedure designer to send email to that user.
Select the Deliver alerts via e-mail check box if this user should be sent every alert via the
email system.
May 2008
4.
Enter the Distinguished Name and Directory tree where this user’s data can be found.

5.
Select the name of the user to whom this user reports, from the drop-down list in the User
reports to field.
6.
These fields support integration with external directory services.
Any structure you set up here is reflected in the staff hierarchy on the Staff tab. If you make
changes on the Staff tab, those changes are reflected here as well.
Click on the Password button >>, to enter a password for the user.

When users log into the Metastorm Client, they have the opportunity to specify a
password. If no password has been defined, the user leaves the field blank.

If you want your users to have passwords, you must define them in the Users and Roles
application.
3.9
The Lists Tab
If you have a lengthy list of users to add, you may add them as a group using the Lists tab option,
rather than enter each user name individually.
To display the Lists tab, click on its tab extension on the Users & Roles window.

The Lists tab is displayed.
Figure 60: Lists Tab
The Lists tab enables you to perform the following tasks:
•
Create and save a list of previously defined users with a common role.
May 2008
51
•
Enter a list of new users directly into the Lists tab.
•
Add a previously defined list of users to the database.
•
Grant a common role to a list of users.
•
Revoke a common role from a list of users.
3.9.1
Creating a List of Users with a Specified Role through the Lists
Tab
To create a list of users with a specified role:
1.
From the Lists tab, click on the Select button.

The Select Users dialog is displayed.
Figure 61: Select Users
2.
Select the role for which you want to create a list from the drop-down list, and then click on
the OK button.

The tab is updated with a list of registered users who have been assigned that role.
3.
Work with this list as required, using the options available on this tab.
4.
When you are finished working with the list, you can close the list, with the option to save
it to a file, if necessary.
5.
To assign a role to the list of users, click the Grant button.

The Grant Role dialog is displayed.
Figure 62: Grant Role Dialog
6.
52
Select the role to be assigned from the drop down list and click the OK button.
May 2008
All the users in this list have now been assigned the same role. Any users in this list now
have access to To Do or Watch list items as assigned to this role. For example, a group of
temporary employees hired to do computer inventory work could be assigned the same role
in a computer inventory procedure.
3.9.2
Adding a List of New Users through the Lists Tab
From the Lists tab, enter the names of the users in the field on the left of the tab.
1.
To add these users to the database and grant them all the same role, select the Grant
button.
Figure 63: Adding a List of New Users

The Grant Role dialog is displayed.
2.
From the Grant Role dialog, select a role from the drop-down list.
3.
Repeat as necessary to add these users to the database and grant all users in this list as
many roles as apply. (If these users do not share a single role, select <none> from the
Grant Role drop-down list to add them to the database with no role assignments.)
4.
Any roles that are not shared by all members of the list should be assigned individually through the
Users or Roles tabs.
When you are finished working with the list, close the list or save it to a file, if necessary.
May 2008
53
3.9.3
Adding a List of Users from a File through the Lists Tab
User lists previously created and saved through Users and Roles or lists created as text files (.txt)
in an outside application can be opened in Users and Roles.
To load an existing file of users’ names, in the Lists tab:
1.
2.
Click on the Open File button.

The Read list from file dialog is displayed.

The dialog is the standard Windows navigation dialog.
Select the file, and then click on the Open button.

3.
The names in the selected file are displayed. You can work with this list as necessary
using the options available on this tab.
When you are finished working with the list, you may want save your changes. To:
a)
Save the file with a new name, click on the Save File button, and specify the new file name
in the Save list to file dialog.
b) Overwrite your previous file, click on the Close button, and click Yes to save the file. This
saves the file using the existing file name, and closes the list.
3.9.4
Granting a Specified Role to a List of Users through the Lists
Tab
1.
Open or create the required user list using one of the methods described in sections 3.9.2
through 3.9.4.
2.
Click on the Grant button.

54
The Grant Role dialog box Is displayed.
May 2008
Figure 64: Add Users
3.
Select the role you want to grant to these users from the drop-down list, and then click on
the OK button.
If you grant only the role <none>, the user is added to the list in the database with no role
assignments. Role assignments must be made separately.
3.9.5
Removing a Specified Role from a List of Users through the
Lists Tab
To remove a specified role from a list of users:
1.
Open or create the required user list using one of the methods described in sections 3.9.2
through 3.9.4.
2.
Click on the Revoke button.

The Revoke Role dialog box is displayed:
Figure 65: Remove Users
3.
Select the role you want to revoke from these users from the drop-down list, and then click
on the OK button.
If you select “<all roles>” from the drop down list, all roles currently assigned to the list of users
are removed.
If you select “<users>” from the drop-down list, all users on the list are removed from the
database. You will be prompted for confirmation of deletion prior to removal of each user.
May 2008
55
4
SYSTEM ADMINISTRATOR
The Metastorm System Administrator provides a single point of administration for all Metastorm
systems in an enterprise and consists of the following components:
•
Metastorm BPM.
•
Metastorm Query.
•
Metastorm Process Engines.
•
Metastorm Authentication.
4.1
Opening System Administrator
The System Administrator provides the following core functions:
•
Start and stop Process Engines.
•
Specify authentication processes.
•
Run SQL queries through the Query tool.
•
Change Process Engine settings.
•
Examine error messages.
56
May 2008
Figure 66: Main Window
4.2
Metastorm System Administrator Components
The Metastorm components are briefly described below:
•
Metastorm BPM - This component provides a number of shortcuts, categorized by the tab
on which they appear, which are likely to be the most frequently used. It also has a number
of links to useful pages on the Metastorm web site.
•
Metastorm Query - This component is used to execute SQL queries against a database.
However, this is not limited to a Metastorm database – any database can be queried with
this tool, provided a DSN has been set up and authentication information is known.
•
Metastorm Engines - This component provides access to all registered instances of
Process Engines as well as the facility to register additional Process Engines.
•
Metastorm Authentication – This component provides the ability to setup authentication
methods for the various services.
4.3
Metastorm BPM
Selecting the Metastorm BPM item in the navigation pane displays additional functionality in the
details pane. The pane has a number of tabs that assist a user in managing both Metastorm BPM
and the Windows servers.
May 2008
57
4.3.1
Welcome Tab
Figure 67: Welcome Tab
The Welcome tab options provide additional information to help system administrators become
familiar with Metastorm BPM. The options provided are:
•
Metastorm Readme – provides generalized help and release notes on the currently
installed version of Metastorm BPM.
•
Metastorm website – visits www.metastorm.com.
58
May 2008
4.3.2
Maintenance Tab
Figure 68: Maintenance Tab
The Maintenance tab provides shortcuts to information that assists system administrators in their
support of process developers and users.
The options on the Maintenance tab are:
•
Event Viewer – This option provides a link to the Windows Event Viewer at the
Application log.
•
Metastorm Support – This option provides a link to Metastorm’s online support page.
•
Metastorm Newsgroup – This option provides a link to the web page listing all Metastorm
newsgroups.
May 2008
59
4.3.3
Managing Tab
Figure 69: Managing Tab
The Managing tab provides shortcuts to functionality available from other parts of the System
Administrator.
60
May 2008
4.3.4
Tools Tab
Figure 70: Tools Tab
The Tools tab is a convenient grouping of Windows and administrative tools for the system
administrator.
The options on the Tools tab are:
•
ODBC Manager – Opens the ODBC Data Source Administrator.
•
Metastorm Query – Opens the Query.
•
Services – Opens the Services and Applications.
•
Component Services – Opens Component Services.
•
Command Prompt – Opens the Command Line Prompt.
4.4
Metastorm Query
The Query component enables the user to query the database. Query is not limited to a
Metastorm database – any database can be queried using this tool, provided a DSN has been set
up and authentication information is known.
You cannot run stored procedures against an Oracle database through the System Administrator.
Selecting Metastorm Query in the console tree produces two panes – one for SQL and another for
results.
May 2008
61
SQL Pane
Results Pane
Figure 71: Metastorm Query
4.4.1
Query Toolbar
Metastorm Query includes its own toolbar. A listing of all buttons and their functionality is given
in the following table:
Icon
Command
Shortcut
Enables connection to a database by
specifying login, password, and DSN.
Connect
62
Function
Previous
Ctrl + Alt + P
Returns to a SQL query run before the
currently listed SQL pane.
Execute
F9
Runs the SQL query as written in the
SQL pane.
Next
Ctrl + Alt + N
Returns to a SQL query run after the
currently listed SQL query.
Group By Box
Enables the user to group results based
upon one or more columns in the results
pane.
First
Goes to the first result in the Results
pane.
Previous
Goes up one result in the Results pane.
Next
Goes down one result in the Results
pane.
Last
Goes to the last result in the Results
pane.
May 2008
Icon
Command
Shortcut
Function
Cut
Ctrl + X
Clears the current selection and adds
selection to the clipboard.
Copy
Ctrl + C
Adds the current selection to the
clipboard.
Paste
Ctrl + V
Pastes the contents of the clipboard in the
specified location within in the SQL pane.
Undo
Ctrl + Z
Undoes the last edit performed in the
SQL pane.
Redo
Shift + Ctrl + Z
Redoes the edit performed in the SQL
pane.
Open SQL
Enables user to open a previously saved
SQL query.
Save SQL
Saves the current SQL query to file
Print SQL
Prints the current SQL query.
Print SQL Preview
Displays the current SQL query as it
would print, without actually printing.
Save Results
Saves the results to file; defaults to an MS
Excel file.
Print Results Preview
Displays the current Results pane as it
would print, without actually printing.
Print Results
Prints the Results pane.
Help
Opens Query’s help.
Table 2: Query Commands
To query a database, the user must press the Connect button on the toolbar and provide the
authentication information. Once the user is connected to the database, standard SQL queries can
be written in the SQL pane. Query results are displayed in the Results pane when those queries
are run. To switch the database being queried, select the connect button again and provide
authentication information for the new database.
If your query retrieves a BLOB, double-clicking on the field enables you to save the BLOB to a file.
4.4.2
Designing Reports
When you access the Print Results Preview dialog
Design Report
, you can design a report by pressing the
button. This option enables you to update:
•
Generic report options.
•
Report colors.
•
Report fonts.
May 2008
63
•
Report behavior.
4.5
Metastorm Process Engines
When controlling Process Engines through the System Administrator, the user must:

have network administrative rights (to control the services)

be included as a user with the "Administrator" role for the Process Engine COM+ application
(Component services) on the machine which the Process Engine is to be controlled.

be set up in Dcomcnfg as able to access the EngineManager application.
As described in the Installation Guide, this is best done through user management of the global or
local network user group "Metastorm Admins" which is added to the "Administrator" role by default
during the Metastorm BPM installation.
The Process Engines component enables the System Administrator to monitor and maintain one
or more instances of the Engine installed as a service.
To register an Engine, and add it to the list of Engines shown in the System Administrator:
1.
Right-click on Metastorm Engines and select Register…

Register Metastorm Engine dialog appears.
Figure 72: Register Metastorm Engine dialog
2.
In the Register Metastorm Engine dialog, add the name of the computer on which the
Engine is installed, and click on the OK button.
64
May 2008
Figure 73: Active Process Engine running as a service
When a user right-clicks an instance of the Process Engine in the console tree, a popup menu is
displayed as shown below:
Figure 74: Tree Popup Menu
The menu enables the user to commit the following actions:
•
Start – Starts the selected Process Engine.
•
Stop – Stops the selected Process Engine.
•
Restart – Restarts the selected Process Engine.
May 2008
65
•
Unregister –Unregisters the selected Process Engine.
•
Database... – Opens a dialog that enables the selected Process Engine to run against a
different database.
If the engine fails to start when a Oracle database is changed, use regedit to remove
Persist Security Info=False from the registry key
HKEY_LOCAL_MACHINE\SOFTWARE\Metastorm\e-work\Engine\Database
Connectors\Oracle DBC\Connection.
•
Event Logging – Enables you to configure the Process Engine to log errors to the Event
Log or to an Error Log File.
The Engine will write to the Event Log, or a file; not both.
If the specified Error Log File path is invalid, the Engine may not start.
4.5.1
Metastorm Authentication
Authentication provides the system administrator the capability to set up authentication methods
for the various services.
For further details of how to configure open authentication, refer to section 8.
66
May 2008
5
ENGINE
This chapter discusses the operating environment for the Engine and the configuration necessary
to run the Engine as a system service.
5.1
Operating Environment
The Process Engine can be seen as a collection of COM in-process components, which work
together as an application. These components need to run in an operating system process
appropriate for both the application and the Engine components; i.e. the:
•
Engine process should run under an account that determines what the Engine can do on the
system.
•
Security infrastructure should be easily configurable, so the Engine Administrator can
control access to the Engine’s services.
The system that provides this infrastructure is COM+.
This section describes the operating environment for the Process Engine, and covers:
•
How to start the Process Engine.
•
How to check and administer the Process Engine registration and security settings.
•
How to re-register the Process Engine.
5.1.1
Starting the Engine
The core Engine functionality runs as a COM+ application. An executable is provided to start the
application, eEngine.exe – the Engine system service executable.
Installation sets this up to determine when the Engine starts and stops.
May 2008
67
In addition to this Engine starter application, there is the COM+ application, which hosts the
Engine’s COM+ components and the .NET Common Language Runtime (CLR), as illustrated in
the following diagram:
COM+ Application
(Dllhost.exe)
+
+
Starter Application
+
(Engine Service)
.NET CLR
+
Engine's COM+ components
Figure 75 : Engine Starter Application and COM+ Application
The .exe file that starts the Engine COM+ application must be running under an account with
sufficient access rights to communicate with the application. This account does not need
administrative rights; the Engine can run under an account with user privileges. This account
must have the following access privileges for the Engine registry key and its sub-keys:
•
Query Value
•
Set Value
To grant these privileges:
1.
Open the Registry Editor by typing regedt32 in to the Windows Run dialog.
2.
Navigate to the registry key HKEY_LOCAL_MACHINE\Software\Metastorm\ework\Engine.
3.
Right click on Engine and select the menu item Permissions….
4.
Add the user account you intend to use to run the Engine.
5.
With the user highlighted in the Name list, click the Advanced… button. The Access
Control Settings dialog appears.
6.
Select the relevant user, and click on the View/Edit… button. The Permission Entry dialog
appears.
68
May 2008
7.
In the Permissions list, ensure that the Allow checkbox is checked for Query Value and Set
Value.
8.
Ensure these permissions are set for each sub-key of the Engine registry key.
For further information on:
•
Roles, refer to section 0
•
Setting up an administrative security structure for Metastorm BPM, refer to section 0.
Additional configuration steps for Windows XP
When configuring a web client to connect to an Engine, the identity of the ‘IIS Out-Of-Process
Pooled Applications’ or ‘IIS-{Default Web Site//ROOT/escripts}’ COM+ Application must be
configured.
This also applies to any Metastorm component hosted in IIS, when communicating with the
Engine, for example, the HTTP Listener.
The identity of the ‘IIS Out-Of-Process Pooled Applications’ or the ‘IIS-{Default Web
Site//ROOT/escripts}’ COM+ Application account must be configured as a client of the remote
Engine service.
If the protection on the web server’s web extensions virtual folder (by default, escripts) is set to:

High (Isolated), update the ‘IIS-{Default Web Site//ROOT/escripts}’ COM+
Application identity.

Medium (Pooled), update the ‘IIS Out-Of-Process Pooled Applications’ COM+
Application identity.
Otherwise, trying to connect to a remote engine using DCOM produces the following error:
Invalid data for a node of type 'CDATA'
5.1.2
Troubleshooting: Problems Starting the Engine
COM+ problems starting the Engine are reported in the event log. For full problem reporting, we
suggest you set full auditing of failures.
To set full failure auditing:
1.
Start the Local Security Policy snap-in by selecting the Windows Start | Control Panel |
Administrative Tools | Local Security Policy.
May 2008
69
2.
Navigate to Local Policies | Audit Policy in the Tree, as shown below:
Figure 76 : Local Security Settings
3.
Set failure auditing for each of the items in the details pane, by:

Double-clicking the item in the details pane

Checking the checkboxes in the Local Security Policy Setting dialog.
Some common problems starting the Engine are discussed in the following sections. They are:
•
Inability to start Engine.
•
‘Access is denied’ error when attempting to connect.
•
‘.NET database connector failed to initialize’ error
Inability to Start Engine
This can occur because the Engine application’s identity is ‘Interactive User’ and an attempt is
made to start the Engine (for example, automatically as a service) when nobody is logged on to
the machine. To resolve this, change the identity to something other than ‘Interactive User’.
‘Access is denied’ error when attempting to connect
When attempting to connect, an ‘Access is denied’ error may occur in the application or system
event log.
This occurs when an account, without the necessary role, requests communication with the
Engine (usually a client without the Client role attempting to connect to the Engine).
This is resolved by ensuring the account either:
•
Has the required role
•
Becomes a member of a Windows user group that holds the role.
70
May 2008
For the web client, if a web server is connecting to:
•
A local Engine, the connecting account will be the one specified in the Anonymous User
settings of the IIS Admin tool
•
An Engine via DCOM (i.e. on a remote machine), the connecting account will be the
launching account as specified in the COM+ identity for the escripts virtual folder.
When role-based security is enabled on the Engine, the escripts virtual folder should be configured to
Medium or High isolation so that a launching account is available through the respective COM+
package.
Changed COM+ settings do not take effect until the Engine application is restarted.
A related problem can occur when the Engine attempts to communicate with another application
via COM, for example:
•
During a Microsoft Word mail merge
•
Creating a COM object using server-side scripting.
Again, if the Engine’s account does not have sufficient rights to communicate with the required
COM server, access is denied.
This is resolved by accessing the dcomcnfg utility (part of Windows) and changing either the:
•
Application security settings.
•
Default security settings.
.NET database connector failed to initialize
This error can occur with an Oracle database. Possible reasons are:
•
The .NET provider has been updated.
•
The .NET providers were selected during the installation of the OLEDB driver for the
Oracle 10G R2 client.
In either case you will need to uninstall and reinstall the Oracle client, as well as the ODBC and
OLEDB drivers.
Oracle Administrators should make sure that the Oracle.DataAccess and related
Policy.x.x.Oracle.DataAccess files have been removed from the GAC after the 10G R2 client has been
uninstalled. This advice assumes that only one Oracle home has been installed on the machine.
5.1.3
Troubleshooting: Engine Failure
If the Engine fails during operation, a message will be written to the event log.
You may see the following log message after an Engine failure:
May 2008
71
Unhandled exception thrown from a .NET Script or Workflow:
<caught exception message from failed script>, This has
caused the Metastorm Engine to stop. Please restart the
Engine.
This can occur when a script spawns one or more additional threads, and one of these threads
thows an exception that it fails to handle.
It is strongly recommended that scripts should handle all exceptions that may occur.
5.1.4
Reviewing Engine Settings
This section enables you to review the following settings:
•
Settings applied when registering the Engine COM+ application is registered.
•
Security settings.
These settings can be reviewed and updated using the Windows administrative tools Component
Services.
Reviewing Engine Registration Settings
To review the results of Engine registration, in the System Administrator:
1.
Start the ‘Component Services’ application.
2.
Navigate to the ‘Metastorm Process Engine’ application.
The ‘Metastorm Process Engine’ application has eight components which, between them,
expose the:

Main functionality of the application.

Four COM+ roles available for the application.
You can now examine the:

Application properties.

Component roles.

COM+ concurrency.
Application Properties
To examine the application properties:
1.
Select the ‘Engine’ application.
2.
Select the Action menu | Properties.
72
May 2008
3.
Select the Identity tab:
4.
Ensure a specific user is named, as system services often run without user intervention (for
example, starting when a machine is booted).
Ensure that the account under which the Engine is configured to run has full rights to:
The following registry key (and all its sub-keys and values):
HKEY_LOCAL_MACHINE\SOFTWARE\Metastorm\e-Work\Engine
The Engine installation folder and sub-folders.
5.
Select the Security tab.
6.
Ensure the Enforce access checks for this application checkbox is checked. This indicates
whether Windows should perform security checks for gaining access to the Engine
application’s components.
This checkbox is checked by default.
For further information on security- related issues, refer to the sub-section on Security below.
7.
Select the Advanced tab.
8.
Ensure the Minutes until idle shutdown radio button is selected.
9.
Ensure the number of minutes is ‘0’, since the Engine service, rather than COM+, manages
the lifetime of the Engine itself.
Component Roles
The Process Engine application has eight components. Each component has one or more COM+
roles defined. The following table lists the components, their purpose, and the roles to which
access may be restricted:
Component
Main purpose
Calling account
requires at least one
of these roles
e-Work.EngineManager.1
Controls lifetime of Engine
Administrator
e-Work.EventManager.1
Deals with requests to raise
flags, and handles timed and
conditional actions
Administrator, Flag
Raiser
e-Work.EworkTransaction.3
Deals with client requests
from whatever source
Administrator, Client
May 2008
73
Component
Main purpose
Calling account
requires at least one
of these roles
eWork.MQ.MQMessageBroker.EMessageBroker
Configures message queuing
integration and sends
messages
Administrator
eWork.MQ.MQMessageBroker.EMQListener
Used by message queuing
integration to process
messages to the Engine.
MQ Notifier
Metastorm.eServiceDirector
Request Broker
Client
Metastorm.EEngineSupportImpl
Manages ECL transactions
Client
Metastorm.RemoteConfiguration2
Manages configuration of
client for ECL transactions
Client , Administrator
Table 3: Components List
If the Engine (COM+) application is:
•
Configured for authorization checking, only accounts holding a relevant role can access its
components.
•
Not configured for authorization checking, no restrictions apply as to which components
can be accessed by which roles.
COM+ Concurrency
When the Engine is installed, it is very important to ensure that each of the Engine components
has Concurrency set so that Synchronization Support is Required. Without this, there is the
possibility of producing an internal deadlock in the Engine.
To verify the Engine components’ Concurrency settings:
1.
Drill-down to the Process Engine application’s components.
2.
Select the required component.
3.
4.
Select the Concurrency tab.
5.
In the Synchronization Support field, ensure the Required radio button is selected.
6.
5.1.5
Security
Refer to the previous section for instructions on how to access the Security tab.
COM+ uses roles, which:
•
74
Define access based on job items.
May 2008
•
Are bound to Windows users or groups.
Role-based access permissions can be defined for each Engine component. The 4 automatically
defined COM+ roles are:
•
Administrator, which has full access to all Engine services. This role should be highly
restricted, as it can start and stop the Engine.
•
Client, which has access to the transaction protocol, used to fulfill most requests.
Typically, this role is held by any user account or group, which needs to communicate with
the Process Engine to do work. Such user accounts could include:

The web server’s anonymous user account.

Any accounts used to run client software.
•
Flag Raiser, which has the ability to raise a flag externally.
•
MQ Notifier, required for using Metastorm BPM with message queuing systems.
Role Checking
Role checking is performed only if the Engine application is configured for authorization
checking.
To ensure role checking is performed:
1.
Start the ‘Component Services’ application.
2.
Navigate to the ‘Process Engine’ application.
3.
4.
Select the Security tab.
5.
Ensure the Enforce access checks for this application checkbox is checked.
6.
Ensure the Security Level is set to Perform access checks at the process and component
level.
Binding Roles to Users or Groups
Binding a user group, rather than specific user accounts, to a role can provide more flexibility.
For example, when a new user joins a team that uses the Client role, if the new user account is
bound to the Client role, the new user can access the Engine only after it has been restarted. In
this case, it may be better to set up a Windows user group called ‘Metastorm Clients’ and bind
this to the Client role. Now, when the new user joins, the user account is simply made part of the
‘Clients’ group.
To see the users and groups bound to a COM+ role:
1.
Access the Component Services main window.
May 2008
75
2.
Navigate to the Roles folder.
3.
Open the relevant role’s folder, then its Users folder.
To add more users or groups to a role:
1.
Access the Users folder for the role, as described above.
2.
Select the Action menu, the New submenu, then the User menu option.
The Select Users or Groups dialog is displayed.
3.
Add users and groups as required, by selecting them then clicking on the Add button.
5.1.6
Re-registration of the Engine
You may need to reconfigure the Engine’s COM+ setup, if:
•
The installation displayed a COM+ error during Engine installation.
•
You wish to return to the default Engine COM+ settings.
The following files are provided, in the Process Engine folder (folder pathway by default,
\Program Files\Metastorm BPM\Engine), to help with Engine reconfiguration:
•
A batch file (register.bat)
•
The EngineConfig utility (EngineConfig.exe), called by register.bat
•
The Metastorm Engine.PAK file, called by EngineConfig.exe.
register.bat
register.bat performs the following actions:
•
Removes the ‘Process Engine’ COM+ application, including the Components and Roles.
•
Registers the COM components of which the Engine is composed. register.bat initially
tries to register each COM component without user acknowledgement (using the /s switch),
but if it fails, it retries without the /s switch so that problems are reported.
•
Registers the Engine application with COM+, which groups the COM components under
the Engine application. It does this by running a utility called EngineConfig.exe. Default
users and groups of users are set up in Roles in the same way as they are set up by the
installation.
EngineConfig
EngineConfig sets up the Engine to run as a COM+ application. For example, you can use
EngineConfig to specify:
•
76
A COM+ application file to describe how the Engine components should be organized in
the application. This may be useful for troubleshooting.
May 2008
•
Engine identity and password.
This subsection describes EngineConfig’s command-line arguments.
/Package:<package file | application file>
Specifies the application COM+ package to install. This is normally a file with .PAK/MSI
extension. (The Metastorm Install comes with a .PAK file, however it is possible for customers to
create their own MSI file to facilitate deployment across a large number of machines)
When specifying the application / package, you must:
•
Specify the full path.
•
If the path contains spaces, surround the entire argument in double-quotes, for example:
"/Package:C:\Program Files\Metastorm BPM\Engine\Metastorm
Engine.PAK"
If you omit the file extension, EngineConfig assumes it is MSI.
If the Process Engine is installed via the Metastorm BPM setup program, avoid using Metastorm
Engine.MSI either in this parameter or directly. Microsoft Windows Installer registers this MSI
as part of the main Metastorm BPM installation and does not permit operations with it by other
programs.
If the Engine package already exists, it is removed before the specified package is installed.
/InstallPath:<installation path>
Specifies where COM+ should place component files. We recommend using the Engine
directory, for example:
"/InstallPath:C:\Program Files\Metastorm BPM\Engine"
This argument is optional. If it is omitted, component files are placed in the system default
location.
/Identity:<account>
Specifies the account under which the Engine should run. In addition, it:
•
Adds the user for this account to all available (COM+) roles for the Engine.
•
Sets Authorization checking, so access to the Engine’s components is restricted by role.
For further information on security, refer to the previous section.
An example of this argument’s use is:
/Identity:MYDOMAIN\ppascal
This argument is optional. If it is omitted:
•
The Interactive User account is assumed.
May 2008
77
•
Users are not added to Engine roles.
•
Authorization checking is left unset.
/Password:<password>
Specifies the password for the account specified with the /Identity argument , for example:
/Password:secret
This argument is optional. If it is omitted, the password is empty.
Alternatively, you can use the /PromptForUserDetails argument.
/BindUserToRole:<rolename:<account | group>>
Specifies an additional user account or group that can hold a COM+ Engine role.
For example, you may want the web server's anonymous account to communicate with the
Engine. In this case, you would use the argument as follows:
/BindUserToRole:Client:CORPORATE\IUSR_CORPSERVER
”/BindUserToRole:Flag Raiser:Metastorm Flag Raisers”
This argument is optional.
/PromptForUserDetails
Specifies that, when EngineConfig runs, it displays a dialog for you to enter the identity (account)
and password for the Engine application to use. If the /Identity: argument is also used, its contents
are the default value in the dialog.
/?
Displays a message box summarizing EngineConfig’s command-line arguments.
Troubleshooting: Problems with re-registration
Problems with re-registering the Engine by running register.bat could arise from:
•
regsvr32, responsible for informing the system about the Engine’s individual COM
components.
•
Using the EngineConfig tool.
Problems Running regsvr32
LoadLibrary (<dll name>) failed. GetLastError returns 0x0000007e
78
May 2008
regsvr32 cannot locate the specified dll, or another dll on which it depends. This implies an
incomplete installation, the best option is usually to uninstall and then reinstall the Engine.
LoadLibrary(<dll name>) failed. GetLastError returns 0x0000045a
A dll initialization routine failed for the specified dll, or another dll on which it depends. This
implies an incomplete installation, the best option is to uninstall and then reinstall the Engine.
Problems Running EngineConfig
Failed to install Package – An error occurred reading the package
file (0x80110408)
This can occur because the:
•
Specified application or package file (usually .MSI or .PAK) cannot be found.
•
Command-line does not include the full path to the package file.
•
Path to the package file includes spaces but is not enclosed in quotes.
For further information, refer to the previous section.
Failed to install Package – Package file path is invalid
(0x8011040a)
This usually occurs because the path specified for the /InstallPath: argument is wrong.
For further information, refer to the previous section.
Problem while trying to save changes to packages collection –
Package identity user ID and/or password are not valid
(0x80110414)
•
Account specified does not exist.
•
Password specified is not correct for the account.
You may need to review the /Identity: and/or /Password: command-line options.
Problem while trying to save changes to role’s user collection –
User ID for user in role is not valid (0x8011040f)
This can occur because the account or group specified in the /BindUserToRole: argument is
invalid.
5.1.7
.NET CLR Configuration
The configuration file application.config, which is installed in the Engine directory, holds
information about how the .NET CLR hosted by the Engine should operate. For the most part
May 2008
79
administrators should not need to alter this file. However, there are a number of settings that it
may be found necessary to adjust; these settings are described in this section.
The settings of interest are shown in the following sample application.config file:
<?xml version="1.0" encoding="utf-8" ?>
<configuration>
.
.
.
.
<appSettings>
<add key="ThreadPool_MinWorkerThreads" value="50"/>
<add key="ThreadPool_MaxWorkerThreads" value="1000"/>
</appSettings>
<runtime>
<assemblyBinding xmlns="urn:schemas-microsoft-com:asm.v1">
<probing privatePath=".\dotnetbin"/>
</assemblyBinding>
</runtime>
</configuration>
Element
Description
<probing
privatePath=”.\dotnetbin;.\dotnetlib”/>
This is a standard .NET CLR configuration setting,
used to specify subdirectories of the Engine’s
directory that might contain assemblies.
Subdirectory names are delimited by semicolons.
<add
key=”Threadpool_MinWorkerThreads”
value=”50”/>
This setting is used to specify the minimum number
of worker threads to be set up in the .NET CLR
thread pool. This thread pool is used when running
Jscript.Net scripts or executing Microsoft
workflows.
On installation, this value is set to25 x (number of
CPUs on machine) x (number of cores per CPU).
The value shown in the example is illustrative only.
The higher the setting for this value, the higher the
resource cost to the Engine process.
Once started, the Engine reports the value it is using
in its startup message in the event log.
<add
key=”Threadpool_MaxWorkerThreads”
value=”1000”/>
This setting is used to specify the minimum number
of worker threads to be set up in the .NET CLR
thread pool. This thread pool is used when running
Jscript.Net scripts or executing Microsoft
workflows.
The higher the setting for this value, the higher the
80
May 2008
potential resource cost to the Engine process.
Once started, the Engine reports the value it is using
in its startup message in the event log.
If you change any of the settings in application.config, you must restart the Engine for these
changes to take effect.
5.2
Configuring the Engine Service
This section describes how to run the Process Engine service and covers troubleshooting the
Process Engine service.
In order for the Engine Service to start up successfully, the account under which the Engine service is
configured must be specified in the Administrator role for the Process Engine COM+ application.
5.2.1
Troubleshooting
This section provides solutions to common errors when attempting to start the Process Engine as
a system service, and covers:
•
1069: The service did not start due to a logon failure.
•
2186: The service is not responding to the control function.
Error 1069: The service did not start due to a logon failure
•
Specified account does not exist.
•
Password specified for the account is incorrect or has changed.
•
Account specified does not have the “Log on as a service” right. This is automatically
granted when setting up the account using the Services application.
Error 2186: The service is not responding to the control function
This occurs because of an invalid service installation. We recommend you uninstall, then reinstall the Process Engine.
May 2008
81
5.3
Engine Registry Settings
5.3.1
Script Timeout
In order to prevent database locking, server-side scripts time out after a definable period, which is
set to 120 seconds by default. This period is specified in the following registry key:
Key: HKLM\SOFTWARE\Metastorm\e-work\Engine
Name: ScriptTimeout (secs)
Type: DWORD
If the value is set to 0, no timeout is set.
If the script times out a user will see the default error message "Failed to commit action" in the
Browser. In addition, the Designer log will have procedure error which states that the script has
timed out. This problem can be solved by increasing the script timeout.
5.3.2
JScript Query Timeout
The number of seconds the Metastorm Process Engine waits for a JScript.NET method to be
invoked can be configured by changing the following registry setting:
Key: HKLM\SOFTWARE\Metastorm\e-work\Engine
Name: JscriptQueryTimeout(secs)
Type: DWORD
If the value is set to 0, no timeout is set.
5.3.3
Activate CallerID
Key:
HKLM\SOFTWARE\Metastorm\e-work\Engine
Name:
ActivateCallerID (0 or 1)
Type:
DWORD
This determines whether the engine uses the identity of the DCOM caller to check the validity of
session IDs. If this is set to:
•
82
0, the engine does not use the DCOM caller ID as part of a session validation. This enables
more than one caller to use the same session ID, which is a requirement for the win32
client’s web forms feature, where the web server needs to be able to share the client’s
session ID.
May 2008
•
1, a session ID is rejected if it is used by a DCOM that did not originally create the session.
In a win32 client environment, this prevents user1 from attempting to use a session id
generated by user2.
A side effect of setting ActivateCallerID to 1 is that Web Forms no longer work.
Changing the ActivateCallerID setting, then restarting the engine, invalidates any sessions already in
the session table.
The default value is 0.
5.3.4
Query Timeout
Key:
HKLM\SOFTWARE\Metastorm\e-work\Engine\Database
Name:
QueryTimeout (secs)
Type:
DWORD
The amount of time the database spends on a query before rejecting it.
Note that not all OLEDB drivers support QueryTimeout.
5.3.5
Login Timeout
Key:
Name:
LoginTimeout (secs)
Type:
DWORD
The amount of time the Engine waits for a database connection to be established.
Note that not all OLEDB drivers support LoginTimeout.
5.3.6
Force Case-insensitive Authentication
Key:
Name:
Force Case-insensitive Authentication
Type:
DWORD
Enables a case-sensitive database to allow case insensitive logins.
If this is set to:
•
0 (default), the Engine does not perform case-insensitive authentication.
May 2008
83
•
1, the Engine performs case-insensitive authentication.
5.3.7
Force Case Sensitive Role Evaluation
Key:
HKLM\Software\Metastorm\e-work\Engine\
Name:
Force Case sensitive role evaluation
Type:
DWORD
If this is set to:
•
0 (default), the Engine does not perform case-sensitive role evaluations.
•
1, the Engine performs case-sensitive role evaluations.
The value defaults to 0.
5.3.8
Fire When Changed On Submit
Key:
Name:
FireWhenChangedOnSubmit
Type:
DWORD
If this is set to:
•
0 (default), a form’s fields’ When Changed events will not fire when the form is submitted.
•
1, a form’s fields’ When Changed events will fire when the form is submitted.
5.3.9
Disable Static Role Resolution
Key:
Name:
DisableStaticRoleResolution
Type:
DWORD
If this is set to:
•
0 (default), static roles are assumed in the eAssignment table.
•
1, static roles are not assumed in the eAssignment table, and all roles have to evaluate to a
list of user names.
84
May 2008
5.3.10
Max Simultaneous Async Jobs
Asynchronous tasks, such as those resulting from calls to the %ScriptAsync, %Print and
%Email functions, can be run simultaneously. This setting specifies the maximum number of
tasks that can be run simultaneously. The default is 5. The maximum is 64.
It is important to be aware of the memory footprint required to run an asynchronous script. If multiple
instances of an asynchronous script are run in parallel, the amount of memory required will be the
footprint multiplied by the number of instances. The memory footprint of a script could be quite large
if other components are created and used by the script.
Key:
Name:
Max Simultaneous Async Jobs
Type:
DWORD
5.3.11
Install Info
This registry key contains a record of information specified by the user and the installation, when
Metastorm BPM is installed.
Key:
HKEY_LOCAL_MACHINE\SOFTWARE\Metastorm\e-work\InstallInfo
Name:
InstallInfo
Type:
DWORD
After the installation, if you change any of the parameters which have been recorded under the
InstallInfo registry key, you should amend the relevant values under the key. Subsequent
Metastorm BPM upgrades or hotfixes expect the current Metastorm BPM settings to be recorded
under this key.
5.3.12
JScript Precompile Level
As a JScript .NET script can take a long time to compile, this registry key enables you to avoid
performance issues by setting up the Engine to compile all currently available scripts on start-up.
Key:
HKEY_LOCAL_MACHINE\SOFTWARE\Metastorm\ework\Engine\JScriptPrecompileLevel
Name:
JScriptPrecompileLevel
Type:
DWORD
Set the value to:
•
0, for no compilation on start-up
•
1, to compile map assemblies on start-up
May 2008
85
•
2, to compile procedure assemblies on start-up
•
4, to compile map and procedure assemblies on start-up.
You can combine values (by adding them together) to set the registry setting to more than one of
the above. For example, if the value is set to 7 (1 + 2 + 4), map assemblies, procedure assemblies
and map and procedure assemblies are compiled on start up.
5.3.13
Allow Guest User To Raise Flag
In order to raise a flag, an external application must provide either a valid Metastorm user id and
password, or alternatively, a valid session id.
For backwards compatibility, the engine may be configured to relax this restriction and accept
Raise Flag requests without any credentials. This requires that the Guest User is set up.
Key:
HKEY_LOCAL_MACHINE\SOFTWARE\Metastorm\e-work\Engine
Name:
AllowGuestUserToRaiseFlag
Type:
DWORD
Set the value to:
•
0, to force flag raisers to provide credentials.
•
1, to allow flags to be raised without providing credentials.
5.3.14
Microsoft Workflow Timeout
Key:
Name:
MicrosoftWorkflowTimeout (secs)
Type:
DWORD
This defines the maximum length of time for which a Microsoft Workflow instance is allowed to
execute before it is aborted. The default timeout value is 60 seconds.
5.3.15
Microsoft Workflow Enabled
Key:
Name:
MicrosoftWorkflowEnabled
Type:
DWORD
Set the value to:
86
May 2008
•
0, to disable Microsoft Workflow
•
1, to enable Microsoft Workflow
5.4
Administrators are encouraged not to amend this setting.
Engine and Invalid XML
The Engine operates on data that invokes Unicode format. The Engine cannot handle invalid
characters contained in XML scripts. The following Unicode character values create invalid XML
characters:
•
1-8
•
11-12
•
14-31.
Although it is difficult for users to type these non-printable characters, they could be pasted into a
field.
In the event that the Engine is presented with one of these characters, one of the following Engine
errors may be reported in the Event Log:
•
Invalid non-printable character found in an XML fragment. It is strongly recommended that
a suitable alternative is used, otherwise, the performance will be impacted.
•
Failed to load server data.
•
Failed to load decoded server data delta into a DOM.
•
Unable to load XML into DOM. Error(-1072896760) : An invalid character was found in
text content.
5.5
Engines and Time Zones
A Metastorm Client derives its local time from the time difference between itself and each service
to which it connects. For this reason:
•
All the Process Engines in a particular service must be in one time zone, and Daylight
Saving Time should be disabled for these Engines (although database and web servers may
operate under any time zone, and with or without the use of Daylight Saving Time.)
•
We recommend the time of a service is not changed while users are offline.
If a service needs to support only users in a single time zone, or many time zones for which
Daylight Saving Time is always applied on the same date (such as in the European Union),
Daylight Saving Time can still be applied on the Engines in that service.
May 2008
87
5.6
Database Connections
The following database connections are used by the Engine:
•
A single database connection for each Client request. The lifetime of the connection is the
lifetime of the request.
•
A single database connection for each Event Manager request. The lifetime of the
connection is the lifetime of the request.
•
Two database connections, used by the Alert Generator. These connections are held
continuously by the Alert Generator.
•
Two database connections, used by the Event Manager. However, these are created only on
demand (unlike the Alert Generator’s connections).
Additional database connections may be generated by external database calls (for example,
%ExecSQL where a DSN is specified) or from a script, where the author has decided to do their
own database handling.
If tracking the numbers of database connections held, note that COM+ database pooling means that
the numbers of connections held over time is 'smoothed out'.
The Engine supports Unicode character formats but it is able to support non-Unicode formats
when using external databases.
5.7
Event Manager
The Event Manager is an asynchronous component in the Metastorm engine which processes
system events, invoking system actions (flagged actions, conditional actions and timed actions) as
required. System actions are operations which are scheduled by the engine and are stored in the
eWait table.
The Event Manager can be configured to run with multiple threads which is particularly useful on
systems where system actions may take considerable time to complete (such as actions that use
scripting to communicate with external applications).
5.7.1
Configuring the Event Manager
The Event Manager is started during the engine’s startup sequence. The Event Manager creates
the number of threads defined in the registry setting HKEY_LOCAL_MACHINE\SOFTWARE\
Metastorm\e-work\Engine\Event manager\Thread count
The Event Manager can be configured via the registry settings to allow the following modes of
operation:
•
88
On Demand. This is the default configuration. Notifications to perform system action
processing occur when the system deems it necessary. Specifically, if an engine is
configured to handle events on demand, then it relies upon receiving submit requests from
May 2008
clients to activate timer/conditional processing; or else flags being raised against this
engine to do flag processing.
•
Polling. This mode tells the engine to check every n seconds to see if there are system
actions which need processing. This may be useful on an engine dedicated to back-end
processing, which may not perform as many actions as a client-facing engine.
•
Disabled. The Event Manager component is not started on this engine. This configuration
allows an engine to be dedicated to handling client requests.
For an engine with the Event Manager set to Disabled, it is still possible for flags to be raised
(queued) and for system actions to be registered. However, there is no Event Manger running on this
engine to process them.
On start-up, the engine’s name and Event Manager configuration are written to the eEngineName
and eEventManagerConfig columns of the eActiveEngine table. Having these settings mirrored
in the eActiveEngine table allow an administrator to check the configuration of an entire
Metastorm BPM system through a single database query.
When the engine is told to shutdown, the Event manager is notified. All threads are shut down
before the engine exits.
5.7.2
Event Manager Registry Settings
The following registry settings can be configured on each engine:
Poll Interval (secs)
Key:
HKEY_LOCAL_MACHINE\SOFTWARE\Metastorm\
e-work\Engine\Event manager
Name:
Type:
DWORD
Value:
By default, set to 0. If the value is set to a non-zero value, engine will
pro-actively look for any events (timers, conditionals, flags) which need
processing every n seconds.
Thread count
Key:
Name:
Thread count
Type:
DWORD
Value:
This can be set values between 1 and 64. Used to specify the number of threads
dedicated to the event manager.
May 2008
89
Batch size threshold for thread
Key:
Name:
Type:
DWORD
Value:
This key controls the number of requests handled by an individual thread. The
Event Manager uses the value to determine how many threads should be used to
handle a batch of requests.
For example, if the batch size is set to 5 and there are 22 requests then 5 threads
will be used. If the batch size is set to 10 and there are 22 requests then 3 threads
will be used. (The forgoing assumes that the event manager’s thread count is set
to a value of 3 or more).
If the Event manager is using a single thread, this key is set to 0.
Disabled
Key:
Name:
Disabled
Type:
DWORD
Value:
By default, set to 0. Setting this to non-zero value indicates that this particular
engine does not perform system action processing (timed actions, conditional
actions, flagged actions). However it will still add events to the eWait and
eRaisedFlag tables in the usual way.
5.8
Alert Generator
The Alert Generator maintains visibility of ToDo and Watch Lists for each user as folders are
moved from stage to stage. When an action is performed, an alert request is made which is added
to the eAlertRequest table. The alert requests are processed asynchronously in the order that they
have been submitted.
The Alert Generator is started during the engine’s startup sequence. The number of threads to be
used for processing requests is defined in the registry setting KEY_LOCAL_MACHINE\
SOFTWARE\Metastorm\e-work\Engine\Alert Generator\Thread count
On start-up, the engine’s name and Alert Generator configuration are written to the
eEngineName and eAlertGeneratorConfig columns of the eActiveEngine table.
90
May 2008
The Alert Generator can be configured via registry settings to allow the following modes of
operation:
•
On Demand. This is the default configuration. The operating system event which causes
alert processing to occur is signaled when an alert request is added to the queue (the
eAlertRequest table). This happens when an action is performed by this engine (usually
moving a folder from one stage to another) which requires the alerts for a particular folder
to be re-evaluated.
•
Polling. This tells the system to prod the Alert Generator every n seconds to see if any alert
requests need processing. This may be useful on a system dedicated to back-end
processing, which may not perform as many actions as a client-facing engine.
•
Disabled. The Alert Generator component is not started on this engine, and the Alert
Generator is not invoked. As a consequence no alert processing is ever done by this engine.
This may be useful for a client-facing engine, dedicated to handling client requests.
An engine with a disabled Alert Generator will still queue alerts. However, there is no Alert
Generator running on this engine and therefore the alerts will not be processed on it.
•
N/A. The system is not configured to do alert generation. None of the Alert Generator
components on any of the engines in this system are started, and therefore no alert
processing is performed on this system.
5.8.1
Alert Generator Configuration Columns
The Alert Generator can be configured to change the way the engine works on the whole system
by configuring the following columns in the eServer table:
•
•
eDoAlertGeneration

Data type: Numeric.

Default value: -1

-1 The Metastorm BPM system supports alert generation.

0 Alert generation is not supported and alert requests are not queued.
eDeleteDeletionAlerts

Data type: Numeric.

Default value: 0

0 Deletion alerts are marked in the eAlert table with a tilde (~) character.

Non-zero value. Deletion Alerts are deleted from eAlert table.
Deletion alerts are only required for Windows clients that cache user alert information locally. Noncaching clients (like the Web Client and Web Parts for SharePoint) do not use deletion alerts.
May 2008
91
5.8.2
Alert Generator Registry Settings
The following registry settings can be configured on each engine:
Key:
e-work\Engine\Alert Generator
Name:
Type:
DWORD
Value:
By default, set to 0. If the value is set to a non-zero value, the engine will
pro-actively look for alert requests to handle every n seconds.
Thread count
Key:
Name:
Thread count
Type:
DWORD
Value:
This can be set values between 1 and 64. Used to specify the number threads
dedicated to the event manager.
Key:
Name:
Type:
DWORD
Value:
This key controls the number of requests handled by an individual thread. The
Alert Generator uses the value to determine how many threads should be used to
handle a batch alert request.
For example, if the batch size is set to 5 and there are 22 alert requests then 5
threads will be used. If the batch size is set to 10 and there are 22 alert requests
then 3 threads will be used. (The forgoing assumes that the event manager’s
thread count is set to a value of 3 or more).
92
If the Alert Generator is using a single thread, this key is set to 0.
May 2008
Disabled
Key:
HKEY_LOCAL_MACHINE\SOFTWARE\Metastorm\ e-work\Engine\Alert
Generator
Name:
Disabled
Type:
DWORD
Value:
By default, set to 0. Setting this to non-zero value indicates that this particular
engine does not perform alert processing (process alert requests in the eAlert
table). However it will still add alert requests to the eAlertRequest table in the
usual way.
5.9
Custom Notification
The Metastorm BPM system designer can implement customized notification when an action is
committed. It consists of a Metastorm BPM expression which is evaluated whenever an action
has been successfully committed.
The customized notification is stored in the eNotification column which is a memo field
found in the eServer table. By default it is empty.
The customized notification is not specific to any particular procedure or map; nor is it specific to any
particular type of action.
If the evaluation of the eNotification expression fails for any reason, the state of the folder is
not affected, specifically the fact that it has been successfully committed. The failure is simply logged
in the normal way.
5.9.1
Custom Notification Example
The Metastorm BPM system designer could decide to bypass the standard alerts mechanism,
implementing customized notification. This might be achieved by:
•
Telling the Metastorm BPM system not to process alerts, via the
eServer.eDoAlertGeneration value.
•
Providing a script function called ActionNotify that implements the new mechanism,
and supplying an expression for eNotification, for example:
%ScriptAsync(VBScript,,AcmeNotification,AcmeNotification,"Act
ionNotify",)
This would mean that ActionNotify would be called asynchronously every time an action is
committed. This would require no changes to be made to any of the other procedures.
May 2008
93
6
ROLLING OUT THE MAIL CLIENTS
A separate installation package, MailClientsSetup.exe, is provided for installing only the
Metastorm mail clients.
This package can be run:
•
In the normal way, with the Metastorm BPM installation.
•
Silently (without a user interface) using predefined parameters, for mass deployments.
Mixed mode installation (i.e., changing the command line to make it interactive, while still specifying
installation settings) is not supported.
To distribute Clients to end users’ computers, you:
•
May need to run the installation with elevated privileges.
•
Can specify command line arguments with which to run the installation.
6.1
Elevated Privileges
To install a Mail Client on a computer where the user does not have administrator rights, the
installation must be run with elevated privileges.
For further information, refer to Microsoft’s on-site documentation on ‘Installing Office with
Elevated Privileges’.
94
May 2008
6.2
Specifying Install Parameters
You can specify, from the command line, parameters which automate the installation of the Mail
Clients.
To run a silent install, type the following at the command line:
MailClientSetup.exe /s /v/qn
To specify parameters for a silent installation, type a command similar to the following at the
command line:
MailClientSetup.exe /s /v"/qn
ADDLOCAL=eWorkOLClient,eWorkNotify"
Quotes are necessary when the properties for the /v argument contain spaces.
6.2.1
The /s Argument
The /s argument runs the installation in silent mode, which does not create any Windows user
interface, including the initial progress bar.
6.2.2
The /qn Argument
The /qn argument does not create a Windows user interface, except for an initial progress bar.
6.2.3
The /qb Argument
The /qb argument works in the same way as the /qn argument, except that it displays a
progress bar during the installation. It is an alternative to the /qn argument.
6.2.4
The /v Argument
The /v argument passes command line switches and public properties to the Windows
Installation service.
Key Public Properties
The following table summarizes possible values for key public properties:
Property
INSTALLDIR
Value
Folder for the installation.
the default value is <ProgramFiles>\Metastorm BPM
May 2008
95
Property
ALLUSERS
Value
Whether to perform a per-machine or per-user installation on Windows-based
target systems. If this property is set to:
•
1, configuration data is written to the All Users profile if the user has
administrative privileges. If not, the installation displays an error
message and then exits.
•
2, the configuration data for the installation is stored in the All Users
profile, if the user has administrative privileges or, otherwise, to the
current user's profile.
If this property is not set, it defaults to 2.
ADDLOCAL
List of features, separated by commas, that are to be installed locally. Possible
values are ALL or comma-separated eWorkOLClient, eWorkNotify,
which allows selective installation of the Metastorm Client for Microsoft
Outlook, and Metastorm Notify respectively.
In addition, you should add eWorkClientComponents and
eWorkMDACClient. So, the default value is:
ADDLOCAL=eWorkClientComponents,eWorkMDACClient,
[comma separated list of Clients to be installed]
We also recommend you add the following log-in switches:
/Livecpaurw %TEMP%\e-Work6MClog.txt
So, the command line for installing the Metastorm Outlook Client, for example, is:
/v"/qb
ADDLOCAL=eWorkClientComponents,eWorkMDACClient,eWork
OLClient /Livecpaurw %TEMP%\e-Work6MClog.txt"
EBYPASSLAUNCH
CHECKS
By default the installation checks to ensure that installation prerequisites (as
specified in the Installation Prerequisites / Supported Environment Guides) are
present and reports an error if they are not. If this property is set to 1 then this
check is bypassed.
Clients List Provider Settings
The following properties define Client-Engine connectivity.
For further details, refer to the ‘Configuring Metastorm BPM Parameters’ section.
ESLPMACHINE
Machine name or IP address (default value the name of the machine installer
is run on).
EHTTPDCOM
Connection method.
Possible values are DCOM (default) and HTTP.
EPORT
HTTP port number for the HTTP connection method. The default value is
80.
EVRHTTPLISTENE
R
Name of the IIS virtual root hosting the Metastorm HTTP listener
(eMessageHandler.dll) on the machine specified in ESLPMACHINE. The
default value is escripts.
Table 4: Key Public Properties
96
May 2008
7
ADMINISTRATION OF METASTORM
CLIENTS
This section describes the administration of the Metastorm Windows Clients, and covers:
•
Setting services options.
•
Miscellaneous administrative tasks.
For details of how to set general options for the client applications, refer to the user guides
for each of the client applications.
7.1
Configuring the List of Available Metastorm Services
Metastorm Clients can log into more than one service simultaneously, using a facility called
Single Point Access.
The Client connects to a Service List in order to obtain:
•
A list of available services
•
Details of how to connect to each service.
For further information about Service Lists, refer to the Deployment Guide.
The Metastorm Engine supports a number of client access protocols to facilitate this connection.
For client applications that use Transaction Protocol (TP) to communicate with the Engine, the
protocols used are:
•
DCOM
•
SOAP
•
HTTP
May 2008
97
In addition, newer clients that are written to use the Engine .NET Interface may use one of the
following protocols:
•
Direct Access
•
Remote High Performance
•
Remote Open
The following table summarizes the protocols supported by each client that ships with Metastorm
BPM:
Client
Outlook
Type
TP
Protocols
DCOM, HTTP
Notify
TP
DCOM, HTTP
Web
TP
DCOM, HTTP1, SOAP
Web Parts2
.NET Interface
Direct Access, Remote High Performance, Remote Open
Table 5: Protocols supported by each client
The Service List Configuration file (EngineServiceConfig.xml) determines the protocol that a
client uses to connect to a particular Metastorm service.
By default the EngineServiceConfig.xml file is located in \Program Files\Metastorm BPM\IIS
Extensions
7.1.1
Service List Configuration File
For Windows clients, the location of the service list configuration file is set in the Options dialog.
For the Web Client, the location of the service list file is set in the web.config configuration file in
the web virtual folder. By default, the web.config file’s location is \Program Files\Metastorm
BPM\Web folder.
For the SharePoint Web Parts, the location of the service list file is stored in the web.config file of
the top-level content root folder of the default web site in the Windows SharePoint Services
(WSS) deployment.
Web Client, and SharePoint Web Parts
To specify the location of the service list file:
98
1
The TP HTTP listener is not Unicode compliant. For full support of extended characters, select DCOM or SOAP.
2
The Metastorm Web Parts use the Web Client to render forms.
May 2008
1.
Open the web.config file in Notepad.
2.
Update the ServiceList key in the appsettings section. The value should be the
location of the EngineServiceConfig.xml service list file.
If the Engine and web server are on the same computer, the location of the service list
should be referenced liked this:
<add key=”ServiceList” value=”<Metastorm Installation
Directory>\<path>\EngineServiceConfig.xml”/>
If the Engine and web server are on separate computers the service list may be referenced
via direct file access or HTTP. For example:
<add key=”ServiceList” value=”\\<Engine Computer
Name>\<Path>\EngineServiceConfig.xml”/>
or
<add key=”ServiceList” value=”http://<Engine Computer
Name>/<Virtual Directory Alias>/EngineServiceConfig.xml”/>
Service Configuration Attributes
The following table provides a description for each of the attributes in the Service List
configuration file:
Tag Name
Description
<ServiceList>
Container tag that holds one or more <Service> tags.
<PreAuthenticatedRaiseFlag>
This is a reserved tag and should not be changed.
<HTTPUseSoap>
Configures the ‘Remote Open’ protocol used to connect to the
Engine’s .NET interface to use SOAP or binary formatting.
<Service>
Contains all necessary details about one particular Service. The
Service is identifiable by the Name and Description attributes.
<Engine>
Each Engine has a name attribute (e.g. ‘Marketing 1’) to distinguish it
from other Engines within the service.
<Transport>
Method of transport with which to connect to the server. This is held in
the Type attribute.
<Server>
DCOM only.
Server on which the Engine is located.
If the text is left blank, the server is local.
<EndPoint>
SOAP only.
The URL to the Engine’s web service (TPWebService.asmx)
<HTTPServer>
HTTP only.
Server on which the HTTP Listener (eMessageHandler) is installed.
If the text is left blank, the server is local.
<Port>
HTTP only.
Port on which the HTTP server is listening; usually 80.
May 2008
99
Tag Name
<TransactionURL>
Description
HTTP only.
Location of the eMessageHandler.dll on the IIS web server box, for
example:
/escripts/eMessageHandler.dll. If you install the HTTP listener in a
different virtual folder (such as Scripts) then ensure this path matches.
<ProxyServer>
Proxy server name.
<ProxyPort>
Proxy port name.
<ProxyUser>
Proxy user name.
<ProxyPWD>
Proxy password.
Second Transport node:
HTTP only.
With HTTP access, there is a second transport node below the one
that defines the details of the web server. This second node describes
the location of the engine relative to the web server machine. This
node can be either HTTP or DCOM but is usually DCOM.
Table 6: Tags in the EngineServiceConfig.xml File
Engine .NET Interface Clients
There are three configuration options for a .NET client:
•
Direct Access –Applies where the Client and Server are installed on the same host.
•
Remote High Performance – The .NET Interface server side component is hosted directly
in the Engine process. Firewall restrictions may render this option unusable.
•
Remote Open – The .NET Interface server side component is hosted by IIS and
consequently the only supported protocol is HTTP. By default messages are binary
formatted (which provides the most efficient data encoding), but SOAP may be used in
order to overcome firewall restrictions. The Remote Open configuration may be a better
option when large numbers of concurrent users are expected because IIS is optimized for
scalability.
The following service list configuration file extracts show the three .NET Interface connection
methods:
Direct Access
<Service Name="example" Description="Engine via .NET direct access">
<Engine Name="Engine1">
<Transport Type="Remoting">
<Server>ipc://ECLService/ECL.rem</Server>
</Transport>
</Engine>
100
May 2008
</Service>
Remote High Performance
<Service Name="example" Description="Engine via .NET TCP/binary">
<Server>tcp://[ComputerName]:4001/ECL</Server>
</Transport>
</Engine>
</Service>
Remote Open
<Service Name="example" Description="Engine via .NET HTTP/IIS">
<Server>http://[ComputerName]/[ECLVirtualFolder]/
ECL.rem</Server>
</Transport>
</Engine>
</Service>
Where [ComputerName] is the name of the machine on which the Process Engine is running.
[ECLVirtualFolder] is the IIS virtual folder name for Process Engine .NET clients
(‘BPMEngine.NET’ by default)
The ‘Remote Open’ protocol may be configured to use SOAP rather than binary formatting. This
must be done on both the client and server. To configure the client to use this protocol, the
<HTTPUseSOAP> attribute in the service list file must be changed from ‘false’ (the default) to
‘true’.
May 2008
101
Configuring Engine .NET Interface to use SOAP
By default the Engine .NET Interface is configured to use the binary protocol. This protocol is
optimized for performance. However, for .NET clients connecting to an engine through a
firewall, SOAP may be preferable.
To configure the engine to use the SOAP protocol, open the Web.config file (in Program
Files\Metastorm BPM\ECL.NET by default) and change the formatter reference from ‘binary’ to
‘soap’, as shown below.
<channel ref="http">
<serverProviders>
<formatter ref="soap" typeFilterLevel="Full"/>
</serverProviders>
</channel>
Service List Configuration File Example
The following example service list configuration file lists three services:
•
Local.
•
Marketing (which comprises two engines using the same database, both accessed using
DCOM by TP clients, and Remote High Performance mode by .NET clients)
•
HR (which has one Engine, accessed using SOAP by TP clients, and Remote Open mode
by .NET clients).
Each service in this list offers two ‘Transport Type’ methods, one method is for TP clients (which use
DCOM, SOAP, or HTTP). The second (‘Remoting’) transport type caters for .NET clients. .
<?xml version="1.0" encoding="UTF-8" ?>
<ServiceDirectorConfig Name="Metastorm Engine Service List">
<HTTPUseSOAP>false</HTTPUseSOAP>
<ServiceList Type="Engine">
<Service Name="Local" Description="Metastorm Service on my machine">
<Engine Name="MyEngine">
102
May 2008
<Transport Type="DCOM">
<Server>PPASCAL</Server>
<!-Machine Name for local or remote machine
-->
</Transport>
<Server>tcp://PPASCAL:4001/ECL</Server>
</Transport>
</Engine>
</Service>
<Service Name="Marketing" Description="Marketing Service">
<Engine Name="Marketing1">
<Server>MKTG1</Server>
-->
</Transport>
<Server>tcp://MKTG1:4001/ECL</Server>
</Transport>
</Engine>
<Engine Name="Marketing2">
<Server>MKTG2</Server>
May 2008
103
-->
</Transport>
<Server>tcp://MKTG2:4001/ECL</Server>
</Transport>
</Engine>
</Service>
<Service Name="HR" Description="Human Resources Service via SOAP">
<Engine Name="HR2">
<Transport Type="SOAP">
<EndPoint>http://HR1/escripts/
TPWebService.asmx</EndPoint>
<ProxyServer />
<ProxyPort>80</ProxyPort>
<ProxyUser />
<ProxyPWD />
</Transport>
<Server>http://HR2/ECLVirtualFolder/ECL.rem</Server>
</Transport>
</Engine>
</Service>
</ServiceList>
</ServiceDirectorConfig>
104
May 2008
The following example shows how to connect to the HR service via HTTP.
<Service Name="HR" Description="Human Resources Service via
HTTP">
<Engine Name="HR1">
<Transport Type="HTTP">
<HTTPServer>HR1</HTTPServer>
<Port>80</Port>
<TransactionURL>/escripts/eMessageHandler.dll
</TransactionURL>
<ProxyServer/>
<ProxyPort/>
<ProxyUser/>
<ProxyPWD/>
</Transport>
<Server>HR2</Server>
</Transport>
</Engine>
</Service>
If the EngineServiceConfig file has been installed on a remote machine, ensure that the <Server> tag
contains the name of the machine on which the engine is situated. If the <Server> tag is empty,
Metastorm BPM will attempt to connect to an engine local to the client’s machine rather than local to
the machine that holds the EngineServiceConfig file.
The path in an HTTP Service’s< TransactionURL> tag should reflect the correct web server
extensions virtual folder. If the default path of ‘escripts’ is changed during the installation, the
contents of this tag must be updated to reflect the correct virtual folder.
Service names cannot contain any of the following characters:

‘\/: *?"<>|
May 2008
105
Updating the default service
The Outlook Client is configured to connect to a service called ‘Metastorm BPM Server’. If you
update the default service name in the Service List, each user must retrieve the new Service List
when they run the Client.
However, you can pre-configure the Clients to connect to specific services by adding registry
settings to the Client machine. For each service that you wish the user to connect to, add the
following registry key:
HKEY_CURRENT_USER\Software\Metastorm\e-work\Win32
Clients\Shared\EClientMgr\Services\<Metastorm BPM Service Name>
Add the DWORD values outlined in the following table:
Name
Type
Values
ConnectTo
DWORD
1 if the Client is to connect to the service, otherwise 0.
Refresh Interval
DWORD
The hex value in minutes. The default is 0000000F (15 minutes).
Table 7: Service registry setting
7.1.2
Configuring HTTP Connection for TP Clients
Unlike DCOM connections between clients and the Engine, HTTP connections involve a multistep process:
1.
The client application communicates with a HTTP Listener service using HTTP
2.
The HTTP Listener relays the request to either:
•
The Engine using DCOM
•
Another HTTP Listener service, using HTTP, and so on, until the request finally
reaches the Engine.
Each link between the client and the engine is configured in the Service List Configuration file.
In the example in the previous section, the ‘HR’ engine has two <Transport> tags:
•
The first one describing the link between a client and the HTTP Listener service (which
resides on the server ‘HR1’)
•
The second one describing the link between the HTTP Listener and the Engine (which
resides on the server ‘HR2’).
7.1.3
Load Balancing
When a service contains more than one Engine, load balancing is automatically performed
between each of the Engines. The Engine servicing the request is selected at random.
106
May 2008
The ‘Marketing’ service example earlier in this section shows a single service with multiple
engines.
7.2
Clearing the Most Recently Used Forms List
To clear the contents of a user’s most recently used list (i.e. in the case where a service name has
changed):
•
Web client, delete cookies from the browser
•
Outlook client, remove all entries in the following registry key:
HKEY_CURRENT_USER\Software\Metastorm\e-work\Win32
Clients\OutlookMRU
7.3
Setting Client Font Sizes
The same font size should be set on client computers as on the server. This helps to avoid an
issue where forms do not format correctly as the server renders in one size of font while the
clients render a different size.
7.4
7.4.1
Troubleshooting the Web Client
Viewing Error Messages
In order to view error messages in the Web Client turn off the Show Friendly HTTP Error
Messages setting by un-checking the setting in Internet Explorer’s Internet Options.
7.4.2
Windows NT login dialog appears when using web forms
This issue may occur on computers running Windows XP or Server 2003. By default, these
operating systems use Kerberos authentication. If, during the Web Client’s operation, a Kerberos
ticket is passed from the client to the web server and is deemed invalid, the login dialog appears.
The solution is to configure the Web Client so that Kerberos authentication is successful. To
determine the necessary configuration changes, refer to the Microsoft documentation at the
following URLs:
•
http://www.microsoft.com/resources/documentation/iis/6/all/proddocs/en-us/sec_security.mspx
•
http://www.microsoft.com/resources/documentation/iis/6/all/proddocs/enus/sec_auth_intwinauth.mspx
•
http://www.microsoft.com/downloads/details.aspx?familyid=80a1b6e6-829e-49b7-8c02333d9c148e69&displaylang=en
May 2008
107
As a work-around, Kerberos authentication can be disabled on the web server, and clients can be
forced to authenticate using NTLM. To do this:
1.
Log in to the web server as an administrator.
2.
At the command prompt, navigate to c:\Inetpub\AdminScripts.
3.
Enter the following command:
cscript adsutil.vbs set w3svc/NTAuthenticationProviders
"NTLM"
1
Configuring the web server to operate in NTLM mode prevents clients authenticating
via Kerberos to this web server.
7.4.3
Browser Closes
In Internet Explorer 6, if there are too many records in a grid displayed on a form, the browser
may close.
This problem is resolved by using Internet Explorer 7.
7.5
Allowing Multiple Outlook Users from One Installation
If the Client for Microsoft Outlook is installed with an account that has Administrator privileges,
whenever another user logs into Windows on the same machine, a dialog will be displayed asking
whether the user wishes to configure the Metastorm extensions for Outlook.
If a number of users share the same machine, only one user on the machine can use the off-line
features of the Metastorm Client for Outlook.
7.6
Setting the Session Time-out Period
If a user attempts to access a service after a set period of inactivity, Metastorm BPM displays a
message telling them that their session has timed out and that they must log out and log back in
again.
If the user is accessing Metastorm BPM with Outlook any open forms will be closed when they
log out, and any data that has not been submitted will be lost.
If the user is accessing Metastorm BPM with Internet Explorer using the Web Client, they may
leave a form open while logging out and logging back in, and then continue working with the
form.
Users of the Web Parts must close any open forms when the session times out, as any open forms
will be using an out-of-date session id.
108
May 2008
The session times out if the user does not interact with a service for a set period. The following
are examples of interacting with a service:
•
Refreshing a list
•
Opening a folder
•
Submitting a folder
•
Entering data and moving to another field when there are dependencies
However, carrying out the following actions are not counted as interacting with a service:
•
Spending a long time entering data into a field
•
Adding or retrieving an attachment
Note: The session will not time out when Metastorm BPM is taken offline.
Note: For users of the Outlook client, the session will only ever time out if the refresh interval is set to
0 or set to a length of time longer than the time-out period.
The session time-out setting for an Engine is held in the database. To update this setting, open the
‘Update Time-out’ Administration Form, enter the time period in the Session time-out field and
submit the form. The default value for this setting is 60 minutes. If the value is set to 0, the
session will not time out. The change only takes effect for sessions started after the update is
made.
1
We recommend that for security reasons you do not set the session time-out value to 0.
In addition, if the session time-out value is set to 0, the eSession table will fill up with
unexpired sessions and should be cleared manually at regular intervals.
The setting corresponds to the length of a time-out period. The first time-out period begins when
the user first interacts with Metastorm BPM. If the user stops interacting with Metastorm BPM
during the first half of the time-out period, the session ends when this time-out period ends.
For example, if the session time-out is set to 60 minutes, and the user interacts with Metastorm
BPM for just 20 minutes, the session will time out 60 minutes after it began (i.e. 40 minutes since
the user’s last interaction with Metastorm BPM). If the user attempts to interact with Metastorm
BPM after this, he will be asked to log out.
A new time-out period automatically begins the first time the user interacts with Metastorm BPM
during the second half of a time-out period. This new time-out period is treated in the same way
as the first one. If the user carries out their last interaction with in the second half of a time-out
period, the session will continue to be available until the end of the next time-out period.
For example, if the time-out period is set to 60 minutes, and the user interacts with Metastorm
BPM for 45 minutes, the interaction that happens in the 31st minute sparks a new time-out period.
The session will time out at the end of the new time-out period, 1 hour and 31 minutes since the
first interaction. However, if the user starts to interact during the second half of the second timeout period, a further time-out period will begin.
May 2008
109
7.7
Setting Up Automatic Refresh of Alerts Lists in the Web
Client
To Do and Watch lists in the Web Client can be automatically refreshed after a user has
committed a folder action. If this feature is set up, the alerts lists will be refreshed when the user:
•
Opens a folder from the To Do or Watch list and commits an action
•
Opens a folder from the To Do or Watch list and commits a chained action
•
Opens a folder from the To Do or Watch list and cancels a chained action
•
Opens a folder from the To Do or Watch list and takes a Non-confirm folder action
•
Opens a folder from the To Do or Watch list and takes a Confirm folder action.
7.8
For information on configuring this setting refer to section 9.2.3.
Configuring Globalization Settings in the Web Client
Globalization settings determine how the web clients display dates and numbers, and the
language strings used by the UI. By default, these settings are governed by the user’s browser
preferences. This section describes how to change the settings and the precedence order of the
available settings.
The globalization settings in the Web Client may be configured in a number of ways. The
following table lists the different ways to configure these settings in the order of precedence:
Globalization Setting
External URL query fields
Description
If a form or folder is invoked using an external URL, language and locale
query fields may be included in the URL. If this is done, then these settings
override all other settings. When the resulting form or folder is displayed, it
will always use the settings provided in the URL.
Refer to the Web Author’s Guide for further information on
the external URL’s provided by the Web Client.
Metastorm ‘Browser Settings’
Administration Form
If the Browser Settings administatration form is published and made
available to users, then users may select the date, time, and numeric
settings they wish to use. Submitting this form creates a cookie which
stores these preferences on the user’s local machine. Browser cookies
must be deleted to undo this selection.
The Browser Settings administration form overrides all other settings with
the exception of language and locale query fields passed via external
URL’s.
web.config
The web.config file can be modified by administrators to set the
default date, time and numeric settings, and the default language for all
users.
The administrator sets the culture and uiCulture attributes
for all users. By default these attributes are set to 'auto' which allows users
to set their own preferred language in the browser.
110
May 2008
Browser Preferred Languages
The user is able to set their preferred language if the administrator has set
the culture and uiCulture attributes in the web.config to
'auto'.
Web Client users set their own language and locale preferences using
Internet Explorer’s Language Preferences dialog box.
Table 8: Web Client Globalization Settings
7.8.1
Browser Settings Administration Form
The Browser Settings Administration Form enables an administrator to set the date, time and
numeric settings for the user.
These settings are saved as a cookie on the user's local machine and override the date, time and
numeric settings in web.config and the Internet Explorer's Preferred Language.
By default, the Browser Settings Administration Form is located in the following folder:
C:\Program Files\Metastorm BPM\Administrative Tools\
Administrative Procedure.
For further information on the Browser Settings Administration Form refer to Appendix A of
this document and the Using Metastorm BPM with Internet Explorer guide.
7.8.2
Changing Locale settings in Web.config
The Web Client’s web.config file may be changed to set the preferred language and date,
time and numeric settings for all users. The settings are stored in the <globalization>
child element underneath the <system.web> element.
By default, the <globalization> element has the following attributes:
<globalization culture="auto" uiCulture="auto" requestEncoding="utf-8"
responseEncoding="utf-8"/>
The attributes for language and date and number formats are:
•
culture which specifies the format dates and numbers.
•
uiCulture which specifies the language resources.
If the attributes are set to "auto" and the External URL or Browser Settings administration form
are not used, Internet Explorer's preferred language settings will be used.
Both the culture and uiCulture attributes are specified in the following format which
follows the RFC 1766 standard:
<languagecode2>-<country/regioncode2>
May 2008
111
Where <languagecode2> is a lowercase two-letter code derived from ISO 639-1 and
<country/regioncode2> is an uppercase two-letter code derived from ISO 3166.
For example, change the date, time, number and language settings to German, the German
(Germany) language format is used "de-DE".
<globalization culture="de-DE" uiCulture="de-DE"
requestEncoding="utf-8" responseEncoding="utf-8"/>
The culture attribute must be a specific culture which includes the region code, and not a neutral
culture without a region code. A neutral culture can only be specified in the uiCulture.
Once these settings are in place, the web client will render all dates, numbers and strings in the
specified cultures regardless of the browser’s preferred language settings.
By default, web.config is located in C:\Program Files\Metastorm BPM\Web.
If the web.config does not change the date, time and number settings in Internet Explorer,
deleting all cookies should resolve this issue.
7.8.3
Supporting Browser ‘Preferred Languages’
To enable users to set their preferred language in their browser, the request culture and locale
culture in the Web Client’s web.config file (described in the previous section) must be set to
'auto'. Once this is done, users will be able to control the language string selection and other
culture settings via their language preferences in their browser.
To set language preferences in Internet Explorer, perform the following steps:
1.
Select the Internet Option… item in the Tools menu to open the Internet Options dialog.
2.
Click the Languages… button to open the Language Preference dialog.
3.
Click the Add… button to add one of the languages below:
•
English
•
French
•
German
•
Spanish
4.
Click the OK button to accept the language setting.
5.
Click the OK button to close the Internet Options dialog.
6.
Navigate to the Metastorm web client’s main page. The Metastorm web client displays
dates, numbers and strings in the specified language.
112
May 2008
If the user selects a language that is not supported by the Metastorm web client then dates and
numbers will be formatted in the specified language culture and strings in the default language.
7.8.4
Setting the Default Language
As mentioned in the previous section, if users are allowed to select their language preferences,
then it is possible that they will select a language that is not currently supported by the Web
Client. If this happens then the strings for the default language will be used.
The default language may be set as follows:
1.
Open the web.config file for the Web Client.
2.
Modify the following <add key="Default Culture"> child element underneath
the <appSettings> element:
<appSettings>
...
<add key="Default Culture" value="en" />
...
</appSettings>
The default value is set to English. The value is a culture string specified in the
following format that conforms to the RFC 1766 standard:
<languagecode2>-<country/regioncode2>
and <languagecode2> is a lowercase two-letter code derived from ISO 639 1 and
<country/regioncode2> is an uppercase two-letter code derived from ISO 3166.
For example, the culture identifier for the French (France) language is "fr-FR".
<add key="Default Culture" value="fr-FR" />
If no default language is specified then the Metastorm Web Client will format dates and numbers
using the web server’s regional settings and strings using web server machine’s user interface
language. If the web server’s language setting is not supported by the Web Client, then the Web
Client’s default - English (US) - is used.
7.9
7.9.1
Administering the Metastorm web parts for SharePoint
Server
Introduction
The Metastorm web parts for SharePoint Server allow users to access their alerts and forms lists
alongside other web parts, and to customize their interfaces (if the appropriate permissions have
been granted).
May 2008
113
The SharePoint administrator is responsible for setting up shared web part pages, and inserting
web parts in these pages.
Users with Member permissions may also create their own personal web part pages and customize
their shared pages.
This section covers the following topics:
•
Permissions
•
Adding web parts to a web page
•
Web part global settings
•
Setting the default values of web part properties
•
Setting up Windows single sign-on
•
Advanced UI customization
•
Configuring language and regional settings
•
Configuring alerts and forms lists
•
Catering for visually impaired users
•
Defining custom lists
Metastorm Web Parts do not work in SharePoint unghosted web part pages. Inserting any Metastorm
Web Parts into a SharePoint Web Parts Page that has been customized using Microsoft Office
FrontPage 2003 or any other web part page editing tool will produce an ‘Invalid postback or callback
argument’ error. This is a known issue with WSS 2.0 when the WSS virtual server is configured to
use ASP.NET 2.0.
7.9.2
Permissions
Users of the web parts for SharePoint Server may have Reader permissions or Member
permissions. Users with:
•
Reader permissions may access Metastorm BPM but may not configure the web parts.
•
Member permissions may insert and customize the web parts
These permissions must be configured on the SharePoint server by the SharePoint administrator.
SharePoint Sites with Anonymous Access Enabled
Metastorm web parts do not support anonymous SharePoint users. If the SharePoint site is
configured for anonymous access, there is no way for the anonymous users to login to a
Metastorm BPM engine.
114
May 2008
Logging Errors to the Windows Event Log
The web parts use SharePoint’s application pool user account to log errors to the event log.
Normally the user account that the application pool is using (by default, the Network Service
account) has enough rights to perform this operation.
If this account is restricted or changed to one with insufficient rights then no errors will be
logged. In that case administrators need to grant appropriate rights to allow logging to the event
log by that user.
7.9.3
Adding Web Parts
The following web parts are available to users of Metastorm BPM:
•
Metastorm Service web part
•
Metastorm To Do list web part
•
Metastorm Watch list web part
•
Metastorm Blank Forms list web part
•
Metastorm Admin Forms list web part
•
Metastorm Dashboard View web part
•
Metastorm Custom List web part.
The size of the Dashboard View web part should be the same as its corresponding administration
form. Scroll bars may appear if this is not the case.
The Dashboard View web part does not support the displaying of PDF or HTML external forms,
For optimal performance, all list web parts should be set to a fixed width. This prevents flickering
when the page is refreshed.
All list web parts have a FilterWidth property that sets the width of the filter drop-down. Setting this
property to a non-zero value prevents the filter from re-sizing automatically, and (consequently)
prevents horizontal scroll-bars from appearing if a filter list contains one or more long strings.
The administrator is responsible for setting up shared web part pages for users to access. This
section outlines how to:
•
Create a web part page
•
Add web parts to the web part page
•
Connect the web parts to a service
For information on using and personalizing each Web Part, refer to the Metastorm Web
Parts help.
May 2008
115
Creating a web part page
To set up a web part page:
1.
Log in to the SharePoint site.
2.
Navigate to the area to which the web part page is to be added, or create a new web part
page.
Figure 77: Area to which web part will be added
3.
Click Create on the title bar.
The Create page is displayed.
4.
Click on Web Part Page, in the Web Pages section at the bottom of the page.
Figure 78: Web Pages section
116
May 2008
5.
Follow the instructions on the screen to create a web part page.
Adding web parts
To add a web part to the web part page:
1.
Navigate to the web part page on which to add web parts.
2.
The web part zones are displayed and the Add Web Parts menu is displayed on the right
hand side of the screen.
Figure 79: Web part page showing web part zones
3.
Click the Virtual Server Gallery option.
A list of web parts, including the Metastorm web parts is displayed as shown above.
4.
Insert a web part in one of the following two ways.

Drag the web part to the desired web part zone.

Click the web part, choose the location for the web part in the Add to dropdown and
click the Add button.
For information on personalizing each web part, and the list of each web part’s browsable
properties, refer to the Metastorm Web Parts help.
Connecting the web parts to a service
The Service web part authenticates to the Metastorm Process Engine and establishes a session for
use by the other Metastorm web parts on the page. For this to work, each web part must be
connected to the Service web part.
For instructions on connecting web parts, refer to the ‘Connecting Web Parts’ section of the
Metastorm Web Parts help.
May 2008
117
7.9.4
Web Part Global Settings
In addition to the properties that can be customized using the SharePoint User Interface, the
Service web part requires the following properties to be set in the Web.Config file in the
SharePoint virtual folder.
•
Web Client Base Location, the URL of the Metastorm Web Client.
•
Web Client SSO Location, the URL to which single sign-on requests are routed.
•
Location of the Engine service list configuration file (EngineServiceList.xml)
These properties are read dynamically when a page containing a web part is loaded.
The Web.Config file contains samples of these settings. This file is located in the Program
Files\Metastorm BPM\SharePoint Web Parts directory.
For more details on configuring these settings, refer to Appendix C.
7.9.5
Setting Default Values for Web Part Properties
The default values for all Web Part properties may be set by editing the DWP file for each web
part.
For details on the configuration settings listed in the DWP file for each web part, refer to Appendix E.
7.9.6
Setting up Windows Single Sign-On
The most common method for SharePoint users to authenticate to Metastorm BPM is via
Metastorm Windows Single Sign-On.
Single sign-on must first be set up in order for the web parts to use it. For instructions on
setting up Windows Single Sign-on for Metastorm Web Parts (and other Metastorm .NET
clients) refer to the Windows Single Sign-On Guide.
Configuring the Metastorm Service Web Part to use SSO
In order to use Single Sign-On, you may edit the Service Web Part’s DWP file and set the
UseSSO attribute to the value ‘true’.
Alternatively, you can configure each instance of the Service web part as follows:
1.
Click on the down arrow on the Connector web part.
The web part menu is displayed.
2.
118
Depending on the current view, click on either Modify Shared Web Part or Modify My
Web Part.
May 2008
3.
Click on the name of the Connector web part.
The Modify Web Part menu is displayed.
4.
Set the Use SSO property.
5.
Click the Apply button for the changes to take effect or click the OK button to save the
changes and close the menu.
7.9.7
Advanced UI Customization
In addition to the customization options that may be done via the web part UI, there are a number
of further customizations that may be done by the SharePoint Administrator. These are:
•
Setting Priority Colors
•
Using WSS Themes Support
Setting Priority Colors
To customize the colors of different priorities for alerts:
1.
Locate the following file:
[SharePointWebsite]\wpresources\Metastorm.SharePoint.WebParts
\css\grid.css
2.
Modify the appropriate Customizable Style Sheets (CSS) classes. Each priority uses the
following two CSS classes:

The first one (P followed by the priority number) represents how a normal row appears.

The second one (altP followed by the priority number) represents how an alternate row
appears.
Using WSS Themes Support
WSS themes are supported only to the extent that the colors of the grid header and alternate rows
can be customized.
To customize the colors of the grid header and alternate rows, change the values of the two nonbrowsable properties, AlternatingRowCssClass and GridHeaderCssClass, in the .DWP files for
each web part.
See Appendix E for a full list of the customizable properties contained in the DWP file for each web
part.
These properties represent SharePoint styles in the OWS.CSS cascading style sheet. The default
location for the US English OWS.CSS file is:
May 2008
119
C:\Program Files\Common Files\Microsoft Shared\web server
extensions\60\TEMPLATE\LAYOUTS\1033\STYLES
Note that the initial values, in the .DWP file, have been set to default values.
7.9.8
Configuring Language and Regional Settings
The Metastorm Web Parts use the language configured for the SharePoint site. The web parts are
shipped with support for the following languages:
•
English (EN) (this is the default language)
•
German (DE)
•
Spanish (ES)
•
French (FR)
Web parts will always attempt to display language strings that match the language settings of the
page they are placed on. However, the title of each web part comes from its DWP file. So, if for
example, the German version of the Web Parts is installed and used on a page where the language is
set to French, then French strings will be displayed everywhere but in the web part title. The DWP
file may be edited to change the string displayed as the title of the Web Part.
Creating additional language resource assemblies
All language resource strings for web parts and ASP .NET server controls are kept in the
Metastorm.SharePoint.Resource.dll assembly. By default, this file can be located in the
following directory:
C:\Inetpub\SharePoint\bin
To create additional satellite assemblies, the following are needed:
•
A computer with the Microsoft .NET Framework SDK installed.
For version information, refer to the Supported Environments guide.
•
A copy of the Metastorm Web Parts language resource file for a particular language.
This file changes with each release (when new strings are added) and is not available as part of the
product installation. However, it may be requested from the Metastorm Help Desk. Please see the
Release Notes for contact details.
To create a web part resource satellite assembly:
1.
Set the path for the Microsoft .NET Framework SDK. For example:
@set path=%path%; “C:\Program Files\Microsoft Visual Studio
8\SDK\v2.0\Bin”
2.
120
Use resgen.exe to create the .resource file. For example:
May 2008
Resgen strings.ja-jp.txt
This will create a file called:
Strings.ja-jp.resources
3.
Use al.exe to create the satellite assembly:
al.exe
/t:lib
/embed:<resource file>,
Metastorm.SharePoint.Resources.Strings.<culture>.resources
/culture:<culture>
/out:Metastorm.SharePoint.Resources.resources.dll
where <resources file> is a resources file and <culture> is the culture string,
such as “ja-jp”.
4.
Once the satellite assembly is created, physically copy the DLL to the following directory
in the SharePoint IIS web site:
\bin\<culture>\Metastorm.SharePoint/Resources.resources.dll
where <culture> is the culture string, such as “ja-jp”.
Additional resource assemblies need to be signed by Metastorm. For further information contact
Metastorm Customer Services.
Time Zone Support
Date and time contents of the web parts are adjusted to the SharePoint site time zone, not the
browser time zone.
7.9.9
Configuring Alerts and Forms Lists
There are a number of web part configuration properties common to the To Do / Watch / Blank
Forms / Admin Forms lists that rely on the names of the columns that the engine returns to the
client. These are:
•
WhereFilter – filters the list of items displayed
•
OrderBy – determines the list order
•
Columns – determines the list of columns to be displayed
A To Do or Watch List web part may use any of the following fields in its WhereFilter,
OrderBy and Columns properties:
Column Name
eUserName
Data Type
text (100)
May 2008
121
Column Name
Data Type
eFolderID
text (31)
ePriority
0 to 9
eAlertTime
Date Time
eDeadline
Date Time
eMapName
text (31)
eStageName
text (31)
eFolderName
text (31)
eCategory
text (31)
eSubject
text (250)
eAlertMessage
text (250)
The following is an example of a where clause expression for an alerts list:
eAlertTime > {ts '1999-12-30 00:00:00'}
Similarly, a Blank or Administration Forms List web part may use any of the following fields in
its WhereFilter, OrderBy and Columns properties:
Column Name
eGroupName
Data Type
text (31)
eProcedureName
text (31)
eMapName
text (31)
eFormType
text (1) B[lank] or A[dmin]
eActionName
eUserPage
text (31)
text (250) Form name;
? for confirmation dialog only
! for immediate commit
eDescription
text (250)
The following is an example of a where clause expression for a form list:
eDescription IS NOT NULL
7.9.10
Catering for Visually Impaired Users
The web parts may be used with the JAWS screen reader. To configure a web part page for
visually impaired users:
1.
If you are not already in Shared view, switch to it by navigating to the web part page and
clicking on Modify My Page and then Shared View.
2.
Navigate to the Service web part.
122
May 2008
3.
Enable Jaws support by setting the Enable Jaws Support property.
7.10 Document Management Support (DMS)
Metastorm BPM provides a Document Management Support (DMS) system to enable DMS
Providers to interact with Metastorm BPM processes.
The use of DMS is not supported on a cross domain network. If the DMS has been set up on a domain
named DOMAIN1, for example, only users connected to DOMAIN1 will be able to use the DMS.
Consequently, Metastorm BPM must be installed on the same domain as the DMS with which it is
intended to interact.
Metastorm BPM provides features for Microsoft Office SharePoint Server 2007 and Windows
SharePoint Services 3.0 to enable SharePoint to act as a Metastorm BPM client.
Metastorm DMS has been configured to work with Windows Single Sign-On.
For further information on configuring Windows Single Sign-On for Metastorm BPM, refer to
the Windows Single Sign-On guide.
The web.config file for the Web Client has been changed as follows for DMS.
<configSections>
<section name="appURLs"
type="Metastorm.Web.Configuration.CustomLinks, Metastorm.Web"/>
<section name="dms" type="Metastorm.Dms.MetastormDmsSection,
Metastorm.Dms"/>
</configSections>
The section name "dms" has been added to the <configSections>
...
<system.web>
<httpModules>
<remove name="WindowsAuthentication"/>
For DMS, <remove name="Windows Authentication"/> should be removed from
web.config.
...
</httpModules>
<httpRuntime maxRequestLength="40000" executionTimeout="300"/>
<authentication mode="Windows"/>
The <authentication mode> should be set to "Windows" for DMS.
...
May 2008
123
</system.web>
<dms
provider="Metastorm.Dms.SharePoint,Version=7.0.0.0,Culture=neutral,PublicKeyT
oken=0fa3cc64eebf4c8b" type="Metastorm.Dms.SharePoint.SPDmsProvider"/>
</configuration>
The DMS provider is defined at the end of web.config.
7.10.1
Opening Microsoft Office Documents using DMS
Opening Office documents from a DMS clip or grid in Internet Explorer does not allow the user
to edit the document in an Office application, for example, Excel or Word. The user is limited to
Read Only functionality.
This is a known Microsoft issue and can be resolved by editing the following registry keys on the
users’ machines.
The following has been extracted from the Microsoft Knowledge Base article and describes the
steps amend the registry:
1.
Quit all Office 2003 and 2007 Office programs that are running.
2.
Click Start, click Run, type regedit in the Open box, and then click OK.
3.
Locate and then right-click the following registry subkey:
HKEY_CURRENT_USER\Software\Microsoft\Office\<version_number>\
Common\Internet
In this subkey, <version_number> corresponds to 10.0, 11.0 or 12.0 for the specific Office version
that is installed. You must create the registry key in the HKEY_CURRENT_USER tree. The same
setting under the HKEY_LOCAL_MACHINE tree has no effect.
4.
Point to New, and then click DWORD Value.
5.
Type OpenDocumentsReadWriteWhileBrowsing, and then press ENTER.
6.
Right-click OpenDocumentsReadWriteWhileBrowsing, and then click Modify.
7.
In the Value data box, type 1, and then click OK.
8.
On the File menu, click Exit to quit Registry Editor.
7.10.2
Opening a DMS Document and Internet Explorer
Opening a DMS document with its related application (for example Word) from a DMS clip or
grid in Internet Explorer may leave an Internet Explorer window open in the background.
To resolve this issue a Microsoft hotfix can be applied so that the blank Internet Explorer window
is closed when the user has finished using it and closes the document.
124
May 2008
This is a known Internet Explorer 6 and 7 Issue. The hotfix is obtained by Microsoft Support on
request. For further information, refer to Microsoft KB936880:
http://support.microsoft.com/kb/936880/en-us
7.11 Custom Lists
A custom list is a grid containing a list of data items. Each row in the grid may contain a number
of columns.
A custom list may also have one or more filters defined that allow the user to filter the list of data
displayed in the grid by selecting from one or more drop-downs.
7.11.1
Custom List Types
There are four types of custom list:
•
Plain - a read-only list.
•
Form - a Metastorm blank form or admin form list. On clicking a row in the list, the
Metastorm form is opened in a new Internet Explorer browser window.
•
Folder - a Metastorm alert list. On clicking a row in the list, the Metastorm folder is
opened in a new Internet Explorer browser window.
•
Link - a list with a hypertext link column. The Uniform Resource Locator (URL)
associated with the hypertext link is generated dynamically using data in the list.
7.11.2
Defining Custom Lists
Custom Lists can be defined in the Designer and apply to procedures, JSR 168 Portlets
and the Metastorm BPM Client for Office.
There are two steps required to configure custom lists:
•
Publish an admin procedure that defines the custom list
•
Drop the Custom List Web Part on a web part page and configure the custom list web part
to display the desired custom list
7.11.3
Publishing Custom List Admin Procedure
1.
Open the Metastorm Designer.
2.
Select File > New > Procedure to create a new procedure or open an existing procedure.
3.
Right-click the “Map” node in the Designer Procedure Explorer to display its context
menu.
May 2008
125
4.
Select Component > New > Administration Form to create a new Metastorm
Administration Form.
5.
Select the “Grid” icon in the Metastorm Form toolbar.
6.
Add a grid field to the Metastorm Administration Form and name it MetDataGrid.
7.
Update the grid field properties to display the custom list columns.
8.
Add another grid field to the Metastorm Administration Form called MetDataFilterGrid.
See the following section for notes on MetDataGrid and MetDataFilterGrid caption naming
requirements for Folder and Form list types.
9.
Update the grid field properties to display the custom list filters.
10.
Select the “Do this” tab in the Administration Form’s Properties window.
11.
Enter the custom list configuration in the “Client extensions” field.
See Appendix D for a complete description of the list types that may be configured, and the
configuration settings to enter for each.
12.
Publish the procedure.
7.11.4
Filtering Custom Lists
Custom Lists can be created to display data for the current user. To configure current user
filtering the MetDataGrid and MetDataFilterGrid need to contain the %User.Name formula.
MetDataGrid
To filter the MetDataGrid by the current user, the process designer should set the "Client
extensions" for the Administration Form to contain the %User.Name formula. This formula
filters the data displayed based on the current user using the <filterList> tag.
For example:
<eDataset type ="Folder">
<filterList>
<filter column="eUserName" value="%User.Name"/>
</filterList>
</eDataset>
Only the %User.Name expression is supported as a filterList filter.
Refer to Appendix D for further configuration settings.
126
May 2008
MetDataFilterGrid
The MetDataFilterGrid displays a subset of the MetDataGrid. To display data for the current
user in the MetDataFilterGrid a formula is added to the Rows property of Grid tab.
To achieve this, the process designer adds the following formula to the Rows property of the Grid
tab of MetDataFilterGrid, eUserName=%User.Name.
Figure 80: Filtering by %User.Name
7.11.5
User Name Filtering Example for the Flight Sample Procedure
This example explains how the %User.Name formula can be used to filter the MetDataGrid
and the MetDataFilterGrid using the Flight sample procedure.
1.
Create two grids called MetDataGrid and MetDataFilterGrid by following steps 1-8 in
section 7.11.3 Publishing Custom List Admin Procedure.
May 2008
127
Figure 81: To Do Action List Admin Form
2.
Select the MetDataGrid.
3.
In Properties, select the Grid tab. Set the properties as follows:
•
Tables
eAlert, Flight
•
Rows
(eAlert.eFolderID=Flight.EFOLDERID) AND
(eAlert.eAlertType=' ')
There are three values for the eAlertType: ! Watch List, ~ delete, <space> To Do List. Refer to the
Metastorm Database Schema document for further details.
•
Order
eFolderID
For Custom Lists, the Order property should not contain the table name.
4.
Select the MetDataFilterGrid.
5.
In Properties, select the Grid tab. Set the properties as follows:
6.
128
•
Tables
eAlert, Flight
•
Rows
(eAlert.eFolderID=Flight.EFOLDERID) AND
(eAlert.eAlertType=' ') AND
(eAlert.eUserName='%User.Name')
Select the “Do this” tab in the Administration Form’s Properties window.
May 2008
7.
Enter the custom list configuration in the “Client extensions” field.
<eDataset type = "Folder">
<filterList>
<filter column = "eUserName" value "%User.Name"/>
</filterList>
</eDataset>
8.
Publish the procedure.
Figure 82: Custom List displayed in SharePoint
In SharePoint the MetDataGrid is displayed with the data and the MetDataFilterGrid is
displayed as options which can be used to filter the grid.
7.11.6
Formatting Custom Lists
When a data grid is defined in the Designer, the following column formatting attributes may also
be defined:
•
Caption
•
Visibility
•
Alignment
In addition, for individual data types the following formatting may also be defined:
•
Date Format (Date / Time / both)
•
Whether or not Time Zone Adjustments should be made
•
Decimal Places
•
Currency Symbol
•
Currency Symbol Position
May 2008
129
7.11.7
Custom List Restrictions
When defining Custom Lists in the Designer, process designers must take extra care in regards to
the following:
Using filters
When a filter is used, the columns in the filter (MetDataFilterGrid) must be columns in the main
grid (MetDataGrid).
When user sensitive custom lists are defined (using %User.Name) then the columns referenced
in the xml fragment must match with ones in the main grid (MetDataGrid).
Failing to meet the requirements above will result in a “Failed to obtain list” error message
appearing during the rendering of the web part.
Captions defined for the columns in the filter are ignored. The caption from the main grid is used
instead. All other formatting information defined in the filter grid is also ignored.
Custom “Folder” List
For priority colors to work correctly the ePriority column must be included in the main grid. If
this is left out then no priority coloring will take place.
To be able to open folders the eFolderID column must be included in the main grid. A client-side
error message will be generated if this is not done.
Custom “Form” List
To be able to open Blank / Admin forms both eMapName and eActionName columns must be
included in the main grid. A client-side error message will be generated if either is missing.
7.11.8
Metastorm BPM Client for Office and Custom Lists
The Metastorm BPM Client for Office works differently to the WSS and Java implementations
and ignores MetDataFilterGrid.
Filtering can be performed on visible columns in the MetDataGrid in the Custom Lists Task Pane in
supported Microsoft Office applications.
For more information on Filtering using Metastorm BPM Client for Office, refer to the
Metastorm BPM Client for Office User Guide.
Setting up Custom Lists for Metastorm BPM Client for Office
Custom Lists are setup for Metastorm BPM Client for Office as described in section 7.11.3
Publishing Custom List Admin Procedure.
130
May 2008
Custom Lists Task Pane displays bold folder names for processes which include Smart Tag
activation. For the folder names to be displayed in bold, the following columns must be added to
the MetDataGrid:
•
eMapName
•
eFolderName
7.11.9
Configuring the Custom List Web Part
The Custom List Web Part’s Admin Form Group and Admin Form Name property must be set to
indicate the Administration Form which contains the custom list definition.
For information on setting this property, refer to the Metastorm Web Parts help.
May 2008
131
8
CONFIGURING OPEN
AUTHENTICATION
Authentication is the process of acceptance of a user by a service. Open Authentication
determines how users authenticate to Metastorm BPM.
For Microsoft SQL Server installations, Open Authentication can be automatically configured by
the installation script.
For Oracle installations, Open Authentication cannot be automatically configured by the
installation script and must be set up manually instead.
Open Authentication is set up from the System Administrator.
1.
Right-click on the Authentication MMC Snap-in and select Connect to connect to the
database.
Figure 83: Connecting to the Database
132
May 2008

2.
Once a connection has been made to the database, a default authentication process is
automatically created by the System Administrator.
A SAP script must be assigned to this default authentication process. To do this, in the
Console Tree right-click on Default Process and select Add Script File.

The Add Script File dialog appears.
Figure 84: Add Scripts dialog
3.
Navigate to the Authentication scripts and select the required scripts and click OK.

Authentication scripts shipped with Metastorm BPM are located in Metastorm BPM |
Engine | Authentication.
The selected scripts are added to the main pane.
The following table lists the SAP scripts that ship by default with the Metastorm BPM
installation:
SAP Script
Clients
Supported
Description
eUser
All
Supports standard authentication against the eUser table in the
database.
eRemPwd
Universal Clients
only (i.e. not Web
Client)
Identical to the eUser script, except that it offers the option to
remember the user’s password.
eRemDetails
Universal Clients
only (i.e. not Web
Client)
Metastorm BPM will remember the last used user name for the
service and automatically populate the User Name field
eRemPwdDetails
Universal Clients
only (i.e. not Web
Client)
Fulfils the functions of both the eRemPwd and eRemDetails scripts
May 2008
133
SAP Script
eGuest
Clients
Supported
Web Client
Description
Allows guest login. This SAP is required to support Public Access.
For more information on Public Access, see below.
eError
All
Returns an access denied error to a user
MQauthentication
MQ
MQ can authenticate against the eUser script, but, if you don't want
to use eUser, the MQauthentication script enables MQ clients (but
no other clients) to authenticate.
Table 9: SAP scripts that ship with Metastorm BPM
1
Note that InstallOA.js is not a SAP script.
The eRemPwd, eRemDetails and eRemPwdDetails scripts store the user's password (weakly
encrypted) in the HKEY_CURRENT_USER registry hive. Appropriate steps should be taken to
secure this area before enabling any of these features.
If an assigned SAP script is updated, it must be removed from the list of authentication processes and
added again before the changes will take effect.
When deciding on the authentication mechanism an organization wants to implement,
it is important to ensure that the case of user id’s is generated consistently by each of
the SAPS that a someone may log in with. For example, if someone logs in via the
eUser SAP the user id in the eOriginator column for folders they create will match the
case in the eUser table (e.g. Marketing\JSmith). However, if the same user then logs in
using the eSSO_Web SAP, the name is always lower-case.
This can be a particular problem when the eUser table is populated from an external
source, like Active Directory (using the Directory Extraction component). The case of
the user id in the eUser table will match the case in the directory.
8.1
Chaining SAP Authentication Scripts
Open Authentication is designed to support multiple authentication mechanisms for different
Clients. A single SAP detects the client type (Web / Windows) and may operate differently for
each client. For example, the eRemPwd SAP does not work for the Web Client. This SAP
detects that the client type is ‘Web’, and defers to the next SAP in the chain.
Chaining also provides the flexibility to enable users to try multiple authentication mechanisms
until they find one that works. For example, a common configuration might be for users to
attempt to authenticate using Windows Single Sign-on. If this fails, (possibly because the user is
working remotely) they should be offered the option to log-in using their User ID and Password.
Chaining SAP Authentication Scripts together is done by adding a number of SAPs under the
same authentication process as follows:
1.
134
In the System Administrator, right-click on the Metastorm Authentication MMC snap-in,
and select the Connect option.
May 2008
2.
Right-click on the Default Process, and select Add Script File. Repeat this a number of
times, and the SAP list for this process will now show two or more scripts as follows:
Figure 85: Scripts in the SAP List
The order in which the scripts are run is indicated by the Order column.
3.
To change the order in which the scripts are run, right-click on Default Process and select
the Reorder Script File option.

The Reorder script files dialog is displayed.
Figure 86: Reorder script files dialog
4.
Use the up and down arrows to change the order of the scripts in the list.
5.
Click OK to save the order.
Once a script has successfully authenticated a user, no further scripts in the chain are run.
eGuest.js should not be added this way. For enabling public access, refer to the following
subsection.
May 2008
135
8.2
Enabling Public Access
Public access is configured automatically by the installation of the ‘Public Access’ feature. Public
Access is selected from the ‘Custom Setup’ screen:
If you add or modify public access, you must restart the Metastorm components or reboot the
computers.
If this feature was selected during the install, and the database type is SQL Server (and the Setup
Now option was selected) then Public Access will already be enabled. Otherwise, it can be
configured using the System Administrator as follows:
1.
Right-click on the Authentication Processes node and select the Public access
properties… option.

The Public access properties dialog is displayed:
Figure 87: Public Access Properties Dialog
2.
Check the Allow Public Access check-box.
3.
Click on the browse button to select a Guest script file. By default, you should use
‘eGuest.JS’.
4.
Enter the Guest Username. When a guest user logs in, this is the user name that they will
be given.
5.
The guest user will hold the Metastorm Guest role. If required, you can assign further roles
using the Users and Roles tool.
8.3
Configuring Digital Signatures
You can also configure Digital Signatures by using the System Administrator, as follows:
1.
Right-click on the Metastorm Authentication snap-in and select the Connect menu option.
2.
Connect to the database.
3.
Right-click on the Metastorm Authentication snap-in again and select the Activate
Signature menu option.
136
May 2008

The browse display to select signature JScript file is displayed.
Figure 88: Select Authentication Signatures
4.
Select the ‘eClientSignature.JS’ script from the Program Files\Metastorm BPM\Engine
folder.
If you modify the ‘eClientSignature.js’ script, you must reconfigure the digital signature in the System
Administrator and restart the web server for changes to take effect.
May 2008
137
9
CONFIGURING METASTORM BPM
PARAMETERS
Parameters set during the Metastorm BPM installation specify the behavior of Metastorm
components. These parameters are described below, with details of how to modify them, postinstallation, without having to uninstall or reinstall components.
9.1
Registry Settings
The registry settings which can be changed are under:
•
HKEY_LOCAL_MACHINE
•
HKEY_CURRENT_USER
These settings can be modified, using the Registry Editor.
To ensure new settings take effect, we advise that you restart the machine after making changes.
Values in [square brackets] are variables.
9.1.1
HKEY_LOCAL_MACHINE
Database
Database parameters define how the process engine connects to the Metastorm database. Two
types of connection are required:
•
ODBC, which uses a DSN that has already been set up using the ODBC Data Source
Administrator.
•
OLE DB connection string.
138
May 2008
You can change the database using the System Administrator (right-click on Metastorm Engines,
select Register and enter the name of the Computer on which the engine is running) Then, tight-click
on the machine name and select Database.
Note that the database user ID and passwords are stored in the registry keys under:
HKEY_LOCAL_MACHINE\SOFTWARE\Metastorm\e-work\Engine
1
We strongly recommend that you secure access to this registry key, as it stores sensitive
information about database connectivity. However, the Process Engine requires access
to these keys. So, when setting security permissions to these keys, please ensure the
users or groups with which the Process Engine's service and COM+ application are
configured have permission to access the keys.
Key
\SOFTWARE\Metastorm\e-work
\Engine\Database Connectors
Name
Values
Current
•
SQL Server DBC
•
Oracle DBC
SQL Server DBC
Key
\SOFTWARE\Metastorm\ework\Engine\Database
Connectors\SQL Server DBC
Name
Values
Provider=SQLOLEDB;
Data Source=[DBServerName];
Initial Catalog=[DBName];
User ID=[DBUserName];
Password=[DBUserPassword];
Connection
If DB Authentication is set to NT Authentication,
Provider=SQLOLEDB;
UserID=[DBUserName];
Trusted_Connection=Yes;
DotNetConnection
User ID=[DBUserName];
Connection Timeout=[DBConnectionTimeoutInSeconds];
If DB Authentication is set to NT Authentication,
Source=[DBServerName];
User ID=;
Password=;
Trusted_Connection=Yes;
DotNetProvider
System.Data.SqlClient
Connection
ODBC;
DSN=Metastorm;
UID=[DBUserName];
PWD=[DBUserPassword];
May 2008
139
Oracle DBC
Key
Connectors\Oracle DBC
Name
Values
Connection
Provider=OraOLEDB.Oracle.1;
Data Source=[DBOracleServiceName];
User Id=[DBUserName];
FetchSize=100;
CacheType=Memory;
PLSQLRSet=1
DotNetConnection
Data Source=[DBOracleServiceName];
User Id=[DBUserName];
FetchSize=100;
Cache Type=Memory;
PLSQLRSet=1;
DotNetProvider
Oracle.DataAccess
Connection
ODBC;
DSN=[DBOracleODBC_DSN];
UID=[DBUserName];
PWD=[DBUserPassword];
For details of the QueryTimeout and Force Case-insensitive Authentication parameters, refer
to the ‘Engine Registry Settings’ section.
140
May 2008
Engine Mail Connectors
Mail Connector registry parameters are used to set up the Process Engine to work with email.
Key
\SOFTWARE\Metastorm\ework\Engine\MailConnector
Name
Values
Connector
For SMTP:
ProgID=ework.
MailConnector.[MailConnectorType (SMTP)] ;
DefaultAddress=[E-mailAddress];
LocaleID=[LocaleID, e.g., 1251];
BodyFormat=[BodyFormat (Text or HTML)] ;
EncodingFormat=[EncodingFormat (TEXT or MIME)] ;
AttachmentEncoding=[AttachmentEncoding
(UUencoded or MIME)]
The Engine examines this string for the first ProgID tag.
It attempts to create an instance of this connector. If it is
successful, this connector is used for all %EMail calls.
If, during the initialization of the Engine, it is unable to
find a Connector string, an appropriate entry is added to
the event log. Until this issue is resolved, the Engine is
unable to send emails and all %SendMail calls are
ignored.
%Email defines the Unicode format to be used for all
email content. Setting Locale id =1252 represents the
western European character set. For other character
sets refer to Unicode definitions, e.g. 1251 is used for
eastern European languages and 65001 (UTF-8) is
suitable for the Russian and Kanji character sets.
Engine Name
To avoid clashes in a multi-engine environment, every Engine must have a unique name.
Key
\SOFTWARE\Metastorm\ework\Engine
Name
Name
Values
[Name (Domain$MachineName)]
Engine Browser Protocol
This setting allows the Engine to construct links to folders when sending alerts via email.
Key
\SOFTWARE\Metastorm\ework\Engine
Name
Browserprotocol
Values
http://[WebServerName]/[IISVirtualScriptsFolder]/e
web.dll/
For further details, refer to the
Installation Guide.
May 2008
141
9.1.2
HKEY_CURRENT_USER
Clients List Provider
The parameter specifies the machine from which the Clients receive information about available
Process Engine services.
Key
\Software\Metastorm\e-work\Win32
Clients\Shared\EClientMgr
Name
List Provider
Values
The name of the machine that is acting as the
Service List Provider. This is usually a machine on
which the Process Engine is running.
For further details, refer to the
Administration of Metastorm Clients
section.
Connection
Method
Set to ‘1’ for DCOM, or ‘2’ for HTTP.
URL
The virtual directory used to access the service list
(only required for HTTP connections)
e.g. /escripts
9.2
9.2.1
The port used to access the service list (only
required for HTTP connections)
Port
Non Registry Settings
Engine Service
To configure the Process Engine service, you can change the:
•
Service start-up mode.
•
Service account (or the account under which the Engine runs).
These settings are configurable through the Windows Services tool.
For further details, refer to your Windows documentation.
9.2.2
Metastorm User Groups
To set up the specific user groups for use with Metastorm BPM, you should use specifically
created (local or domain) groups.
These settings are configurable through:
•
142
the Computer Management tool
May 2008
•
COM+ Metastorm Engine Roles
For further details, refer to the Engine section of this document.
9.2.3
Web Client (Web.Config) settings
The Web Client’s Web.Config file contains a number of application settings that determine its
behavior. By default, this file is located in the \Program Files\Metastorm BPM\Web folder.
Requiring Logins for Attachments from Guest Users
This setting determines whether users using Public Access need to login before they can add, read
and delete attachments.
Key
Enable Public Attachment
Values
•
1, to allow guest users to add, read and
delete attachments without
authentication.
•
0, to require authentication from guest
users, in order to add, read and delete
attachments.
Automatically Refreshing Alerts Lists
This setting enables an organization to turn on the automatic refresh of To Do lists and Watch
lists in the Web Client. With this capability, when a folder is opened from a To Do or Watch list
and an action is taken and committed, the list from which the folder was opened will be refreshed.
Organizations should weigh the benefits of this setting against the impact on performance of the
system of repeatedly refreshing the To Do list.
Key
Auto Refresh Alert Lists
9.2.4
Values
•
1, to enable automatic refreshing of To Do
and Watch Lists.
•
0, to disable this feature.
Web Interface Browser Settings
You can change the format in which the Web Interface presents data.
These settings are configurable through the Browser Settings administration procedure.
For further details, refer to section 7.8.1 Browser Settings Administration Form of this
document and the Using Metastorm BPM with Internet Explorer guide.
May 2008
143
10 CONFIGURING METASTORM NOTIFY
GADGET
The Metastorm Notify Gadget is a Vista gadget which notifies Process Users when new items
appear in their To Do list and displays the number and priority of items in their To Do list.
The Metastorm Notify Gadget settings are set and locked by configuring the
DefaultSettings.xml file. This file contains settings which are also available in the
Options dialog of the Metastorm Notify Gadget.
For further information on the Metastorm Notify Gadget refer to the Metastorm Notify Gadget
user guide.
10.1 Configuring Steps
The configuration steps for modifying the Metastorm Notify Gadget file are as follows.
1.
Rename the Metastorm Notify Gadget file from .gadget to .zip.
2.
Extract the contents to a folder.
3.
Open the DefaultSettings.xml for editing.
4.
Edit the contents of the xml file.
5.
Save the file.
6.
Zip all the gadget files.
7.
Rename the .zip file to .gadget.
8.
Double click the .gadget file to install the Metastorm Notify Gadget.
144
May 2008
10.2 DefaultSettings.xml
The Process Administrator can lock some of the settings in the Options dialog.
<?xml version="1.0" encoding="utf-8"?>
<settings>
<bpmService value="Metastorm BPM Server" locked="0" />
<useSSO value="0" locked="0" />
<thresholds locked="0">
<threshold value="4" />
</thresholds>
<refreshInterval value="5" locked="0" />
<webURL value="http://localhost/Metastorm" locked="0" />
<process value="" locked="0" />
<branding value="1" locked="0" />
<sound value="1" locked="0" />
</settings>
10.2.1
Locking a Setting
To lock a setting, set locked="1".
10.2.2
Connection Settings
There are three settings on the Connections tab which can be configured and locked using
DefaultSettings.xml:
•
Web Client URL
•
Service
•
Windows SSO
Web Client URL
The URL of the Metastorm BPM web client can be set using the following setting:
<webURL value="http://<WebServerName>/<MetastormVirtualFolderName>"
locked="0" />
The default value:
<webURL value="http://localhost/Metastorm" locked="0" />
May 2008
145
Service
The name of the Metastorm BPM engine service can be set and locked using the following string:
<bpmService value="Metastorm BPM Server" locked="0" />
If the Service value is empty, the Metastorm Notify Gadget will automatically select the first service
in the Service List.
Windows SSO
Windows single sign-on can be enabled by setting the useSSO value="1". By default, SSO
is not enabled.
<useSSO value="0" locked="0" />
For further information on Windows SSO refer to the Windows Single Sign-On guide.
Figure 89: Connection tab
146
May 2008
10.2.3
Priority Settings
The Priority Ranges tab can be configured and locked using DefaultSettings.xml. Up to
three ranges can be set to group together priorities. There are nine priorities. The ranges are high,
medium and low and are displayed in the Metastorm Notify Gadget in the Priority Bar
with high=red, medium=yellow and low=green. The ranges are set using threshold
options:
</thresholds>
One Range
To display all priorities, use the following syntax:
</thresholds>
The above example shows that the high priority range will include all priorities.
Two Ranges
To display two ranges, use the following syntax:
</thresholds>
The above example shows that Range 1 (high priority) will include priorities one to three and
Range 2 (medium priority) will include priorities four to nine.
Three Ranges
To display and lock three ranges as high, medium and low priorities, use the following syntax:
</thresholds>
The above example shows that Range 1 (high priority) will include priorities one to three; Range
2 (medium priority) will include priorities four to six and; Range 3 (low priority) will include
priorities seven to nine.
May 2008
147
Figure 90: Priority Ranges tab
10.2.4
Other Settings
All the settings in the Other tab of the Options dialog can be locked and set to specific values.
Each setting is described below.
Process
The Metastorm Notify Gadget can be set to a specific process. For example, to set the process
name to flight and lock the field:
<process value="Flight" locked ="1">
The default value displays all items in the Process User's To Do list:
<process value="" locked="0" />
148
May 2008
Refresh
The Metastorm Notify Gadget can be set to a value of 1 to 60 minutes. The default value is 5
minutes.
<refreshInterval value="5" locked="0" />
Branding
The Metastorm Notify Gadget can be displayed with or without Metastorm BPM Branding. The
default value displays the branding.
Figure 91: With Branding
Figure 92: Without Branding
Sound
Each time a new item is added to the Process User's To Do list, an audio sound can be played. By
default, an audio sound is played:
<sound value="1" locked="0" />
To disable the audio sound, set the value ="0".
May 2008
149
Figure 93: Other tab
150
May 2008
APPENDIX A - ADMINISTRATIVE
PROCEDURES
A set of Administrative procedures are supplied with this release of Metastorm BPM. Each of the
procedures provides useful functionality that can be used ‘out of the box’, or modified to suit your
own organizational requirements.
As we develop other generic procedures, we will post them to the Metastorm website,
www.metastorm.com, where you can download them for your own use.
If you develop a procedure that you want to share with other users, please email it to us together
with a short description. We may periodically post such procedures on our website,
acknowledging the author and providing appropriate contact information.
The following table lists the Administrative procedures (and libraries) that are shipped with
Metastorm BPM:
Name
Description
Libraries
Used
Standard Library
Provides a standard Audit Trail form used by other Administrative
procedures (and available for use in any other procedure).
-
Reporting Library
Provides client script functions used to generate charts and export
comma-separated-values from the contents of a report grid.
-
BizTalk Data Services
Library
Provides functions used with Metastorm BizTalk Data Services.
-
MQ Library
Provides functions used for Message Queue integration.
-
Browser Settings
Library
Provides client script functions for loading and saving user settings to
and from a persistent cookie.
-
Browser Settings
An Administration Form that allows a (browser) end user to alter their
default locale settings, such as: date, time and number formats;
number of entries to show on each page of To Do, Watch, Blank and
Administrative Forms lists; and whether JAWS accessibility support
is required for grids.
Browser
Settings
Ajustes del browser
Spanish language version of Browser Settings procedure.
Browser
Settings
Browser-Einstellungen
German language version of Browser Settings procedure.
Browser
Settings
Preferences du
navigateur
French language version of Browser Settings procedure.
Browser
Settings
May 2008
151
Name
Description
Libraries
Used
Business Activity
Monitoring
A set of Administrative Forms for monitoring the state of any process.
Reporting
Designer Log
A pair of Administrative Forms for reviewing the Process Designer
and Authentication logs.
-
eB2B
A procedure shipped with the EAI Adaptor for Microsoft BizTalk,
which allows a register of trading partners to be established.
-
KPI Dashboards
A set of Administrative Forms that allow the display of metrics
relating to processes.
-
List Maintenance
An Administrative Form for moving and copying To Do and Watch
list entries between users.
-
Line of Business
Reporting
A procedure which provides an Administration Form (Report
Definition) for defining a custom Line of Business report.
-
MQ Administration
(uses the MQ Library)
A set of Administrative Forms for registering and unregistering
message queues.
-
Purge
A map for setting up a scheduled purge of defunct folders and
sessions, along with an Administrative Form for performing the purge
on demand.
Standard
Query
A set of Administrative Forms for retrieving lists of folders (that may
be opened directly from the list) by content (full or partial folder name,
subject and/or originator), status (process, stage and/or priority) and
history (actions performed by specified user since a given time).
-
Service Monitor
A map for performing a monthly check on Metastorm license usage.
Reports and charts of historical usage may be produced.
Standard;
Update Time-out
An Administration Form for setting the session time-out period for
users accessing Clients.
User Profiling
A map that maintains profile information (including self-service
password management) for each user, along with an Administrative
Form for listing all (profiled and unprofiled) users.
Reporting
Standard
Table 10: Administrative Procedures List
Publishing an Administrative Procedure
Locating the Administrative Procedures
All the files necessary to publish the administration procedures are loaded onto your system
during the installation. You may publish them just as you would publish any procedure. By
default, these are installed to:
C:\Program Files\Metastorm\Administrative Tools\Administrative Procedures.
Using the Administrative Libraries
A number of the administrative procedures make use of one or more of the administrative
libraries that are also included with Metastorm BPM. Before publishing these procedures, their
libraries must be published.
152
May 2008
Notes on the Administrative Procedures
Browser Settings
This administrative procedure is also available in the following non-English versions:
•
Ajustes del browser (Spanish).
•
Browser-Einstellungen (German).
•
Preferences du navigateur (French).
This procedure provides an Administration Form that allows any (browser) end user to alter their
default locale settings (date, time and number formats; number of entries to show on each page of
To Do, Watch, Blank and Administration Forms lists; and whether JAWS accessibility support is
required for grids).
The Rows Per Page browser setting applies to read-only grids as well as folder lists.
Changing any settings and then submitting the form will save the changed settings as a persistent
cookie on the user’s machine. Cancelling the form will leave the previous settings unchanged.
Browser settings apply to all services under a web server.
Business Activity Monitoring
This procedure provides, to Administrators and designated (at publication time) process owners, a
set of Administration Forms for monitoring the state of any process.
While a form is displayed, and the user’s criteria are specified, the relevant data is displayed in a
grid on the form. The Display Chart… button launches Microsoft Graph (if installed) to display
the data in the selected type of chart.
To view charts in your browser, you must set the Security level for your Local Intranet zone to ‘Low'.
The following forms are available:
•
Current folders shows the number of folders currently at each (non-archive) stage of a
selected process, summarized by current stage.
May 2008
153
Figure 94. Current Folders Bar Chart
•
Folder originators shows the number of folders originated by each user, for a selected
process, since a specified date.
Figure 95. Folder Originators Line Chart
154
May 2008
•
Mean activity times shows the number of folders which have passed through each stage of a
selected process, and their average stay (in days). It only takes into account folders that
have passed through each stage, not those that are still waiting at a stage.
Figure 96. Mean Activity Times Area Graph
•
Mean cycle times shows the number of folders at each archive stage of a selected process,
and the average time (in days) it took them to reach that stage.
•
Overdue folders shows the number of overdue folders (folders whose deadline is in the
past) at each current stage of a selected process.
Figure 97. Overdue Folders Column Graph
May 2008
155
•
Process loading shows the number of folders on any To Do list, for a selected process,
broken down by current stage. If a folder is on more than one To Do list, then it will be
counted several times.
•
User loading shows the number of folders on a selected user’s To Do list, broken down by
process.
Figure 98. User Loading Column with Depth Graph
Designer Log
This procedure provides the following Administration Forms:
•
Authentication log lists all failed authentication attempts against the service. The Purge
button may be used to delete all entries more than a year old. This form is only available to
Administrators.
•
Designer log lists all procedure definition errors detected at run-time by the service, for a
selected procedure. Selecting a row in the list displays further details. If the row identifies a
folder, then an Open Folder button appears, to let the user open the folder in question. This
form is available to process owners and users with the Administrator role.
eB2B
This procedure is shipped with the EAI Adaptor for Microsoft BizTalk.
It allows a register of trading partners to be established together with the documents that will be
exchanged between the Business Partners.
For further details, refer to the Metastorm EAI Adaptor for Microsoft BizTalk Guide.
156
May 2008
KPI Dashboards
This procedure provides Administration Forms that allow the display of metrics relating to the
overall performance of a process.
The following two Administration Forms are provided to display these metrics:
•
•
Process Performance Dashboard displays information relating to the process selected in its
Process dropdown. Status fields indicate the state of the following in relation to preset
thresholds:

SLA exceeded. This represents the number of folders at non-archive stages whose
deadline (or Service Level Agreement) has been exceeded. Click on the status field to
display a list of these folders.

New folders created (in the last 30 days). This represents the number of new
incidents of the process reported in the last 30 days. It measures how frequently new
items are raised.

Folders awaiting action (for more than 5 days). This represents the number of
folders that have been sitting at their current stage for more than five days. Click on the
status field to display a list of these folders.

Priority 1 items in progress. This represents the number of folders with a Priority of
1, currently at non-archive stages. Click on the status field to display a list of these
folders.

Mean cycle time (over the last 30 days). The cycle time is the time taken for a folder
to go through the entire process and arrive at an archive stage. This status field
represents the average cycle time for the process over the last 30 days. Click on the
field to display a list of the folders that have arrived at an archive stage in the last 30
days.

Number of users with more than 30 items in their To Do list. This represents the
number of users with a To Do list of more than 30 items. Click on the status field to
display a list of these users.
Stage Performance Dashboard displays information relating to the stage selected in its
Stage dropdown. To populate this dropdown you must first select a process in the Process
dropdown. Status fields indicate the state of the following in relation to preset thresholds:

Folders sitting at stage. This represents the number of folders sitting at the chosen
stage. Click on the status field to display a list of these folders.

Folders exceeding deadline at a stage. This represents the number of folders that have
exceeded their deadline at the chosen stage. Click on the status field to display a list of
these folders.

Rate of entry of folders to a stage (over the last 90 days). This represents the number
of folders that have entered the stage over the last 90 days.
May 2008
157
Before these dashboards can be used, the thresholds for each status indicator must be set up using
the following Administration Forms:
•
Set Process Thresholds allows you to set up the Safety and Danger thresholds for each of
the status fields in the Process Performance Dashboard.
•
Set Stage Thresholds allows you to set up the Safety and Danger thresholds for each of the
status fields in the Stage Performance Dashboard.
To set up the thresholds using these forms, select the process and/or stage in the dropdowns and
complete the threshold edit boxes. To save the thresholds, press the Apply button. Alternatively,
submit the form.
When you publish KPI Dashboards.xep, some additional blank forms are displayed on the
Administration Forms list. These forms are opened when you drill-down from the dashboard
Administration Forms. It is not intended that you access these forms directly from the Administration
Forms List.
Line of Business Reporting
This procedure provides an Administration Form (Report Definition) for defining a custom Line
of Business report, for which the user can specify:
•
The process.
•
A (text) custom or standard folder variable for grouping the report. The report contains one
entry for each value of this variable.
•
Whether to report the number of folders in each group.
•
The type of chart for displaying the report in a graphical format.
•
Whether to display a calculated value for each group in the report and, if so, the calculation
type and (numeric) custom or standard folder variable on which to perform the calculation.
The calculation type can be:
•

Total.

Maximum.

Minimum.

Average (mean).

Standard deviation.

Variance.
Whether to display an average (mean) duration for each group and, if so, duration units and
(date-time) custom or standard folder variables defining the start and end of the duration.
The duration units can be:

158
Weeks.
May 2008
•

Days.

Hours.
A title for the report.
Once the report is defined, it can be:
•
Redefined
•
Stored for private use by the originator
•
Published. Once the report is published, it can be displayed by any Administrator or
process owner.
•
Deleted.
When the report is displayed, the relevant data is displayed in a grid on the form. Clicking the
Display Chart… button launches Microsoft® Graph (if installed) which displays the data in the
specified type of chart.
To view charts in your browser, you must set the Security Level for your Local Intranet Zone to
‘Low’.
List Maintenance
This procedure provides, to Administrators, an Administration Form for moving and copying To
Do and Watch list entries between users. Selecting a user ID, process name (or % for all
processes) and stage (or % for all stages) name displays a list of all matching To Do and Watch
list entries. Selecting the ID of another, ‘new’, user makes Move and Copy buttons visible: these
can be used to move or copy all listed entries from the first user to the second.
MQ Administration
This procedure provides Administrative Forms to:
•
Register new incoming message queues.
•
Register new outgoing message queues.
•
Unregister existing incoming message queues.
•
Unregister existing outgoing message queues.
Register In Queue Form
To register an In Queue:
May 2008
159
1.
Enter the Metastorm queue name. This is the name that the Engine uses to refer to the
queue.
2.
Select the Queue type.
3.
If you selected a Queue type of MSMQ:

Enter the Queue path for the in queue, in the form:
<MACHINE NAME>\private$\<QUEUE NAME>

Enter the name of the Admin queue used to register the in queue, in the form:
FORMATNAME:DIRECT=OS:<MACHINE NAME>\private$\e-Work_Admin
4.
If you selected a Queue type of JMS or IBM WebSphere, enter the actual message
Queue name. This name is case-sensitive.
5.
If you selected a Queue type of JMS or IBM WebSphere, then, in the Java web service
section:

Enter the URL for the web service for JMS, which is of the form:
http://<hostname>:<portnumber>/eUMS/services/MessagingService?
wsdl
6.

Enter, in the Retry number field, the number of times a request from the message
queue to the Process Engine should be retried before being moved to the eworkretry or
eworkdeadletter queue.

Enter, in the Retry interval field, the number of milliseconds between the retries.
In the Engine Listener web service section:

Enter the URL for the Engine Listener web service, in the form:
http://<hostname>:<portnumber>/eMQListenerWS_1/eListen
erWS.asmx

If you selected MSMQ as the Queue type, select the Authentication Method.

If you have selected Basic Authentication as the Authentication Method, enter the
required Domain, User name and password.

Enter any required web service configuration Additional Parameters, as name value
pairs separated by semicolons, for example:
<name1>=<value1>;<name2>=<value2>
For details of web service configuration parameters, refer to the Designer User Manual.
7.
In the Process section:

160
Select the Map for the action you want the in queue to activate.
May 2008
8.

Select the Stage for the action you want the in queue to activate, unless the action is a
creation action.

Select the Action you want the in queue to activate.
In the Metastorm Credentials section:

Enter the User name of the user who invokes the process.

Enter the Password of the user who invokes the process.
Register Out Queue Form
To register an out queue for JMS and IBM WebSphere:
1.
Enter the Metastorm queue name. This is the name that the Engine uses to refer to the
queue.
2.
Select the Queue type.
3.
If you selected a Queue type of JMS or IBM WebSphere:
4.

Enter the Queue name of the out queue on the MQ system. This name is casesensitive.

Enter the Java web service URL, which is the same as the URL used in the Java web
service section, for the In Queue.
If you selected a Queue type of MSMQ:

Enter the Queue path for the out queue.
FORMATNAME:DIRECT=OS:<MACHINE NAME>\private$\out_queue

Enter any Additional Parameters.
For details of web service configuration parameters, refer to the Designer User Manual.
Unregister Queues Form
To unregister a queue:
1.
Select the appropriate queue from the Metastorm In queues or the Metastorm Out
queues drop-down.
2.
Click the appropriate Unregister button.
Purge
This procedure provides, for users with the Administrator role, a process for setting up a
scheduled purge of defunct folders and sessions, along with an Administration Form for
performing the purge on demand.
May 2008
161
A ‘defunct’ folder is whose creation action was invoked more than a day previously, but which
has still not been submitted. A ‘defunct’ session is one which has had no activity for the last
twenty-four hours. These conditions typically occur as a result of users closing down their
browsers without logging out or canceling any open forms.
Query
This procedure provides, for all users, a set of Administration Forms for retrieving lists of folders
(that may be opened directly from the list) by content (full or partial folder name, subject and/or
originator), status (process, stage and/or priority) and history (actions performed by specified user
since a given time).
Service Monitor
This procedure provides a map for performing a monthly check on Metastorm license usage.
Reports and charts of historical usage may be produced.
Update Time out
This procedure provides, to Administrators, an Administration Form for setting the session timeout period for users accessing Clients. The default for this setting is 60 minutes. To update the
session time-out period:
1.
Open the Update Time-out Administration Form.
2.
The current setting is displayed in the Session time-out field.
3.
Update the Session time-out field.
4.
Submit the Administration Form.
For further information about the session time-out period, refer to section 7.6 Setting the
Session Time-out Period.
User Profiling
This procedure provides a map that maintains profile information (including self-service
password management) for each user, along with an Administration Form for listing all (profiled
and un-profiled) users.
162
May 2008
APPENDIX B - WEB INTERFACE
REGISTRY SETTINGS
The Metastorm web server registry settings are located in the registry sub-key:
[HKEY_LOCAL_MACHINE\SOFTWARE\Metastorm\e-work\Web Interface\Ver
6.0.0]
The settings are listed in the following table:
Setting
Redirect URL to .NET client
Description
To use old Version 6 external URLs with the latest web
client, this must be set to the URL of the latest web
client. For example:
http://localhost/Metastorm
Table 11: Web Server Registry Settings
May 2008
163
APPENDIX C – METASTORM WEB PARTS
SETTINGS IN WEB.CONFIG
The following settings are required in the MetastormWebParts section of the web.config
file. By default, this file is located in the SharePoint virtual folder:
Key
Definition
WebClientBaseLocation
Metastorm BPM Web
Extensions base URL.
Example Value
<add key="WebClientBaseLocation"
value="http://<host>/<Metastorm>" />
where:
WebClientSSOLocation
Metastorm BPM single
sign-on URL.
•
<host> is the name of the machine where Metastorm Web
Extensions are installed and configured (could be
localhost if on the same machine)
•
<Metastorm> is the name of Web Extensions virtual folder
created in IIS on the machine above
<add key="WebClientSsoLocation"
value="http://<host>/<WinSSOVR>" />
where:
164
•
<host> is the name of the machine where Metastorm
WinSSO is installed and configured (could be localhost if
on the same machine)
•
<WinSSOVR> is the name of the Windows SSO virtual
folder created in IIS on the machine above (as described
in the ‘Create Windows SSO Virtual Folder’ section of the
Windows Single Sign-On Guide)
May 2008
Key
EngineServiceList
Definition
Engine service list
location.
Example Value
<add key="EngineServiceList"
value="http://<EngineMachine>/<eScripts>/EngineServiceConfig.x
ml" />
where:
•
<EngineMachine> is the machine name where the
Process Engine is installed.
•
<eScripts> is the default name of the virtual folder where
the service list config file is located.
Refer to the Administration of Metastorm Clients
section of this document for further information on
configuring service lists.
Table 12: Web.Config Settings
May 2008
165
APPENDIX D – CUSTOM LIST WEB PART
DATASET DEFINITION
The Metastorm Data View Web Part is configured using the following Extensible Markup
Language (XML) definition. This configuration XML is entered in the client extensions section
of the administration form which defines the custom list.
<eDataset type="dataset type">
<!— Only the Link dateset type requires the element below ->
<url target="window name"
windowOptions="window options"
text="link column"
data="column list"
useCurrentContext="context flag">
<![CDATA[ url ]]>
</url>
<filterList>
<filter column=”column name” value=”expression”/>
...
</filterList>
</eDataset>
166
Tables or views used for custom lists must have a primary key or an index.
May 2008
Attribute
Value
Description
dataset type
Required. The following values can be specified in the dataset type attribute:
1. Plain. This is a customized read-only list
2. Form. This is a customized Metastorm blank form or admin form list. On clicking a row
in the list, the Metastorm form will be opened in a new Internet Explorer browser
window. The custom list must include the eMapName and eActionName columns.
3. Folder. This is a customized Metastorm alert list. On clicking a row in the list, the
Metastorm folder will be opened in a new Internet Explorer browser window. The
custom list must include the eFolderID column.
4. Link. This is a customized list with a hypertext link column. The Uniform Resource
Locator (URL) associated with the hypertext link is generated dynamically using data
in the list. This option requires the <url> element to be specified.
These settings are case sensitive.
window name
Required. The target attribute specifies the window name where the contents should be
displayed. A "blank" or missing entry will open a new window.
window
options
Optional. The windowOptions attribute is a list of items separated by commas. Each item
consists of an option and a value, separated by an equals sign (for example,
"fullscreen=yes, toolbar=yes"). The following features are supported:
channelmode = {
yes | no | 1 |
0 }
Specifies whether to display the window in theater
mode and show the channel band. The default is no.
directories = {
yes | no | 1 |
0 }
Specifies whether to add directory buttons. The
default is yes.
fullscreen = {
yes | no | 1 |
0 }
Specifies whether to display the browser in full-screen
mode. The default is no. Use full-screen mode
carefully. Because this mode hides the browser's title
bar and menus, you should always provide a button or
other visual clue to help the user close the window.
ALT+F4 closes the new window. A window in fullscreen mode must also be in theater mode (channel
mode).
height = number
Specifies the height of the window, in pixels. The
minimum value is 100.
left = number
Specifies the left position, in pixels. This value is
relative to the upper-left corner of the screen. The
value must be greater than or equal to 0.
Location = {
yes | no | 1 |
Specifies whether to display the input field for entering
URLs directly into the browser. The default is yes.
May 2008
167
0 }
menubar = { yes
| no | 1 | 0 }
Specifies whether to display the menu bar. The default
is yes.
resizable = {
yes | no | 1 |
0 }
Specifies whether to display resize handles at the
corners of the window. The default is yes.
scrollbars = {
yes | no | 1 |
0 }
Specifies whether to display horizontal and vertical
scroll bars. The default is yes.
status = { yes
| no | 1 | 0 }
Specifies whether to add a status bar at the bottom of
the window. The default is yes.
Titlebar = {
yes | no | 1 |
0 }
Specifies whether to display a title bar for the window.
The default is yes.
toolbar = { yes
| no | 1 | 0 }
Specifies whether to display the browser toolbar,
making buttons such as Back, Forward, and Stop
available. The default is yes.
top = number
Specifies the top position, in pixels. This value is
relative to the upper-left corner of the screen. The
value must be greater than or equal to 0.
width = number
Sets the width of the window, in pixels. The minimum
value is 100.
link column
Required. The text attribute specifies the name of the hypertext link column.
column list
Optional. The data attribute specifies a comma-separated list of column names to
construct hypertext link’s dynamic URL.
context flag
url
168
If the name of a hidden column is included then the custom list displays but the link does
not, leaving the list resembling a 'Plain' custom list type
Optional. The useCurrentContext attribute specifies a Boolean value, true or false,
to indicate whether context data should be appended to the hypertext link URL. If set to
true, the following context data will be appended to the hypertext link URL as query fields:
•
SN=SessionID. Where SessionID is the current Metastorm BPM session id.
•
Service=EngineService. Where EngineService is the name of the name of the current
Metastorm process engine.
Required. The format of the hypertext link URL is specified as a text element within the
<url> element. The hypertext link format string can contain one or more substitution
placeholder in the following format:
May 2008
•
{n}
Where n is a zero-based index. The {n} placeholder is substituted at runtime using values
of columns specified in the data attribute.
For example,
http://localhost/Metastorm/eForm.aspx?Map={0}&Action={1}
filterList
Optional. This element defines a list of filters to further restrict the resulting rows in the
dataset. The filters are parsed during procedure publication and end up in the database in
a form of a SQL where clause. This gets evaluated and becomes part of the original SQL
statement during runtime.
filter
Optional. A column based filter that gets applied on the dataset.
name
Required. The name of the table column to be used.
This must be present in the user’s select statement.
column Required. A valid Metastorm BPM language expression
Only the %User.Name expression is supported.
Table 13: Custom list dataset definition
May 2008
169
APPENDIX E – METASTORM WEB PARTS
PUBLIC PROPERTIES
The following tables list the properties of each of the Metastorm Web Parts. The default values for
each of these properties can be set by opening the corresponding DWP file and changing the value.
Service Web Part
Property
Description
User
Metastorm BPM user name.
Password
Metastorm BPM password.
UseSso
Set to ‘true’ if Metastorm BPM single sign-on should be used. Otherwise
set to ‘false’.
EnableJawsSupport
Set to ‘true’ to enable JAWS support. Otherwise set to ‘false’.
WebClientBaseLoaction
Metastorm BPM Web Client base URL. (See Appendix C).
WebClientSsoLocation
Metastorm BPM single sign-on URL. (See Appendix C)
EngineService
The name of the engine service to connect.
HelpFile
Name of the HTML help file.
DefaultCssClass
Default Cascading Style Sheet class name.
Table 14:Service Web Part Properties
To Do / Watch List Web Parts
Property
170
Description
May 2008
Property
Description
OrderBy
ORDER BY expression used to order the list of alerts.
WhereFilter
WHERE filter expression used to filter the list of alerts.
Page
Default alert page number to display.
PageSize
Alert page size.
Columns
Metastorm BPM alert list columns to display. This property is a
comma-separated list of columns.
EnableFiltering
Set to ‘true’ to allow filtering of the list in the UI, otherwise set to
‘false’.
Layout
Web Part layout. The value should always be empty.
HelpFile
The name of the HTML help file.
SelectedRowBackColor
Background color of the currently selected row. You can use RGB
format or the name of a color. For example, for pale green, you can
enter #98FB98 or palegreen.
SelectedRowForeColor
Foreground color of the currently selected row. You can use RGB
format or the name of a color. For example, for pale green, you can
enter #98FB98 or palegreen.
AlternatingRowCssClass
Cascading Style Sheet (CSS) class name to be used for alternating
rows.
GridHeaderCssClass
CSS class name to be used for the header of the grid.
GridCssClass
CSS class name to be used for the grid.
DefaultCssClass
Default CSS class name.
FilterWidth
Gets or sets the filter’s width. If set to zero then the filter resizes
dynamically so all items in it are visible.
Table 15:To Do / Watch Lists Web Part Properties
Blank / Admin Forms List Web Part
Property
Description
OrderBy
ORDER BY expression used to order the list.
WhereFilter
WHERE expression used to filter the list.
May 2008
171
Property
Description
Page
The page number to display.
PageSize
Number of blank / admin forms per page.
Columns
Gets or sets the Metastorm BPM alert list columns to display. This
property is a comma-separated list of columns.
EnableFiltering
Set to ‘true’ to allow filtering of the list in the UI, otherwise set to ‘false’.
Layout
HelpFile
format or the name of a color. For example, for pale green, you can enter
#98FB98 or palegreen.
Cascading Style Sheet (CSS) class name to be used for alternating rows.
GridHeaderCssClass
GridCssClass
DefaultCssClass
Default CSS class name.
FilterWidth
Table 16:Blank / Admin Forms List Web Part Properties
Dashboard View Web Part
Property
Description
MapName
Map name for the admin form that hosts the dashboard.
ActionName
Action name for the admin form that hosts the dashboard.
HelpFile
Table 17:Dasboard View Web Part Properties
Custom List Web Part
Property
Page
172
Description
List page number to display.
May 2008
Property
Description
PageSize
List page size.
AdminProcedureName
The name of the admin procedure containing the admin form that defines
the custom list dataset.
AdminFormName
The name of the admin form that defines the custom list dataset.
EnableFiltering
Set to ‘true’ to allow filtering of the list in the UI, otherwise set to ‘false’.
Layout
HelpFile
Cascading Style Sheet (CSS) class name to be used for alternating rows.
GridHeaderCssClass
GridCssClass
DefaultCssClass
CSS class name.
FilterWidth
Table 18:Custom List Web Part Properties
May 2008
173