Metastorm BPM Release 7.6

Transcription

1 Metastorm BPM Release 7.6 Administration Guide May 2008 Metastorm Inc.

2 Metastorm BPM Release 7.6 Copyrights and Trademarks 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. inquiries@metastorm.com ii May 2008 Metastorm Inc., 2008

3 Contents Metastorm BPM Release 7.6 Administration Guide Table of Contents 1 Introduction Services Manager Accessing Services Manager Services Manager Window Toolbar buttons Connecting to a Metastorm Database Working with the Metastorm Database Publish Procedure or Library Clear Locks Folder Lock Timeout Purge Alerts Purge Deletion Alerts Diagnostics Designer Log Check Data Libraries Libraries Management Procedures Viewing Procedure Components Deleting a Procedure Purging Stages Resetting Passwords Setting Map Groups Deleting a Map Version Control Folder Operations Sub-folders Working with Metastorm Query Working with Metastorm Migrator Users and Roles Role-based Work Management Identifying the Users and Roles Assignments in Your Organization Identifying Users Identifying Role Assignments Defining Roles The Users and Roles Utility Accessing Users and Roles The Users & Roles Window Users & Roles Menu Options Users & Roles Tabs The Users Tab Checking Roles through the Users Tab...33 Metastorm BPM Release 7.6 May 2008 iii

4 Metastorm BPM Release Adding Users through the Users Tab Adding the Current User through the Users Tab Setting User Details through the User Tab Viewing a User's Role Assignments through the Users Tab Granting Role Assignments through the Users Tab Removing/Changing Role Assignments through the Users Tab Deleting a User through the Users Tab The Roles Tab Checking Roles through the Roles Tab Viewing Role Assignments through the Roles Tab Granting a Role to a User or Group of Users through the Roles Tab Removing a Role from a User or Group of Users through the Roles Tab The Attributes Tab Defining Standard Attributes through the Attributes Tab Defining Custom Relationships through the Attributes Tab The Staff Tab Defining Your Organizational Structure through the Staff Tab Adding New Users to the Staff Hierarchy through the Staff Tab Deleting Users through the Staff Tab Defining Staff Member Details through the Staff Tab The Lists Tab Creating a List of Users with a Specified Role through the Lists Tab Adding a List of New Users through the Lists Tab Adding a List of Users from a File through the Lists Tab Granting a Specified Role to a List of Users through the Lists Tab Removing a Specified Role from a List of Users through the Lists Tab System Administrator Opening System Administrator Metastorm System Administrator Components Metastorm BPM Welcome Tab Maintenance Tab Managing Tab Tools Tab Metastorm Query Query Toolbar Designing Reports Metastorm Process Engines Metastorm Authentication Engine Operating Environment Starting the Engine Troubleshooting: Problems Starting the Engine Troubleshooting: Engine Failure Reviewing Engine Settings Security Re-registration of the Engine NET CLR Configuration Configuring the Engine Service Troubleshooting Engine Registry Settings Script Timeout...82 iv May 2008 Metastorm Inc., 2008

5 Contents JScript Query Timeout Activate CallerID Query Timeout Login Timeout Force Case-insensitive Authentication Force Case Sensitive Role Evaluation Fire When Changed On Submit Disable Static Role Resolution Max Simultaneous Async Jobs Install Info JScript Precompile Level Allow Guest User To Raise Flag Microsoft Workflow Timeout Microsoft Workflow Enabled Engine and Invalid XML Engines and Time Zones Database Connections Event Manager Configuring the Event Manager Event Manager Registry Settings Alert Generator Alert Generator Configuration Columns Alert Generator Registry Settings Custom Notification Custom Notification Example Rolling Out the Mail Clients Elevated Privileges Specifying Install Parameters The /s Argument The /qn Argument The /qb Argument The /v Argument Administration of Metastorm Clients Configuring the List of Available Metastorm Services Service List Configuration File Configuring HTTP Connection for TP Clients Load Balancing Clearing the Most Recently Used Forms List Setting Client Font Sizes Troubleshooting the Web Client Viewing Error Messages Windows NT login dialog appears when using web forms Browser Closes Allowing Multiple Outlook Users from One Installation Setting the Session Time-out Period Setting Up Automatic Refresh of Alerts Lists in the Web Client Configuring Globalization Settings in the Web Client Browser Settings Administration Form Changing Locale settings in Web.config Supporting Browser Preferred Languages Setting the Default Language Metastorm BPM Release 7.6 May 2008 v

6 Metastorm BPM Release Administering the Metastorm web parts for SharePoint Server Introduction Permissions Adding Web Parts Web Part Global Settings Setting Default Values for 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 Document Management Support (DMS) Opening Microsoft Office Documents using DMS Opening a DMS Document and Internet Explorer Custom Lists Custom List Types Defining Custom Lists Publishing Custom List Admin Procedure Filtering Custom Lists User Name Filtering Example for the Flight Sample Procedure Formatting Custom Lists Custom List Restrictions Metastorm BPM Client for Office and Custom Lists Configuring the Custom List Web Part Configuring Open Authentication Chaining SAP Authentication Scripts Enabling Public Access Configuring Digital Signatures Configuring Metastorm BPM Parameters Registry Settings HKEY_LOCAL_MACHINE HKEY_CURRENT_USER Non Registry Settings Engine Service Metastorm User Groups Web Client (Web.Config) settings Web Interface Browser Settings Configuring Metastorm Notify Gadget Configuring Steps DefaultSettings.xml Locking a Setting Connection Settings Priority Settings Other Settings Appendix A - Administrative Procedures Publishing an Administrative Procedure Locating the Administrative Procedures Using the Administrative Libraries Notes on the Administrative Procedures Browser Settings Business Activity Monitoring vi May 2008 Metastorm Inc., 2008

7 Contents Designer Log eb2b KPI Dashboards Line of Business Reporting List Maintenance MQ Administration Purge Query Service Monitor Update Time out User Profiling Appendix B - Web Interface Registry Settings Appendix C Metastorm Web Parts Settings in Web.Config Appendix D Custom List Web Part Dataset Definition Appendix E Metastorm Web Parts Public Properties Service Web Part To Do / Watch List Web Parts Blank / Admin Forms List Web Part Dashboard View Web Part Custom List Web Part Metastorm BPM Release 7.6 May 2008 vii

8

9 Metastorm BPM Version Release 7.6 Administration Guide 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. Metastorm BPM Release 7.6 May

10 Metastorm BPM Release 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 Metastorm Inc., 2008

11 Administration Guide 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: 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 Publish Procedure Clear Locks Folder Lock Timeout Purge Alerts Purge Deletion Alerts Opens a connection dialog to a database. Enables you to select one or more procedure or library (.xep or.xel) files to publish. The procedures cannot be edited. 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. Enables you to specify the number of seconds after which a locked folder in the database is automatically unlocked. 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. 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: Metastorm BPM Release 7.6 May

12 Metastorm BPM Release 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 Metastorm Inc., 2008

13 Administration Guide 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 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 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 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 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: Metastorm BPM Release 7.6 May

14 Metastorm BPM Release 7.6 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 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 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. Deletion alerts are used only by Windows based clients and are therefore not used by users accessing Metastorm BPM through a web browser. 6 May 2008 Metastorm Inc., 2008

15 Administration Guide 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 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). Metastorm BPM Release 7.6 May

16 Metastorm BPM Release 7.6 Figure 6: Diagnostics 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 Metastorm Inc., 2008

17 Administration Guide 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 tree and clicking the Refresh button on the toolbar. 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. If the date checkbox is not checked, all entries are purged. 3. To purge Failed login attempt entries or Procedure error entries, check the appropriate checkboxes. Metastorm BPM Release 7.6 May

18 Metastorm BPM Release Click the OK button. For maintenance purposes, you may want to purge the log on a regular basis, as this is not done automatically 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. The following Check Data reports are available: Figure 10: Check Data reports 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 Metastorm Inc., 2008

19 Administration Guide 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 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. Metastorm BPM Release 7.6 May

20 Metastorm BPM Release 7.6 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 Metastorm Inc., 2008

21 Administration Guide 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 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: Metastorm BPM Release 7.6 May

22 Metastorm BPM Release 7.6 Figure 14: Procedure Components Details of Administration Form sets are available under the Maps item 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 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 Metastorm Inc., 2008

23 Administration Guide 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 Purge Stages button. If folders are present at the stage, an error message is displayed and the purge action is canceled 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. Metastorm BPM Release 7.6 May

24 Metastorm BPM Release 7.6 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 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. The Set Map Groups button becomes available. 2. 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. The Set Map Group dialog is displayed: 16 May 2008 Metastorm Inc., 2008

25 Administration Guide 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. Click the OK button. In the Client application, this set of maps is now available for all users who have access to the group Deleting a Map To delete a map: Metastorm BPM Release 7.6 May

26 Metastorm BPM Release Expand a procedure on the tree; Its maps are displayed in the main pane. 2. Select the map you want to delete. 3. Click the Delete button. Alternatively, select the Delete Map option from the Action 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. When a map is deleted, all the folders associated with it, whether active or inactive are also deleted from the database Version Control 18 May 2008 Metastorm Inc., 2008

27 Administration Guide 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. 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: Metastorm BPM Release 7.6 May

28 Metastorm BPM Release 7.6 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 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). 20 May 2008 Metastorm Inc., 2008

29 Administration Guide 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 Metastorm BPM Release 7.6 May

30 Metastorm BPM Release 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, or right click on the selected folder and select Unlock from the dropdown menu. 3. The folder is unlocked. 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 Metastorm Inc., 2008

31 Administration Guide 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 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. Metastorm BPM Release 7.6 May

32 Metastorm BPM Release 7.6 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. Enter the required database User name and Password. 24 May 2008 Metastorm Inc., 2008

33 Administration Guide 6. Select the DSN for the Metastorm Database. 7. Click on the OK button. 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. The scripts are stored in Metastorm BPM Engine Database which contains SQL Scripts and Oracle Scripts. 10. For the SQL scripts in SQL Query select the required Database, connect to the database and select the SQL Server-create.sql script. Metastorm BPM Release 7.6 May

34 Metastorm BPM Release 7.6 Refer to the Migration Guide for details of Oracle database migration. 11. 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. 12. 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. The new tables are now populated with data. Your database is ready for use with Metastorm BPM Version May 2008 Metastorm Inc., 2008

35 Administration Guide 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. 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. 3.1 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 Metastorm BPM Release 7.6 May

36 Metastorm BPM Release 7.6 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? 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 Metastorm Inc., 2008

37 Administration Guide 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 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 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 Accessing Users and Roles To access the Users and Roles utility, follow these steps: Metastorm BPM Release 7.6 May

38 Metastorm BPM Release 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: The number of registered users in the database. 30 May 2008 Metastorm Inc., 2008

39 Administration Guide 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 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 About Displays information about the version of Users & Roles 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. Metastorm BPM Release 7.6 May

40 Metastorm BPM Release 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 Metastorm Inc., 2008

41 Administration Guide 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: The result of this check either: Figure 36: Check Roles Screen 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 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. 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. 3. Click OK. Metastorm BPM Release 7.6 May

42 Metastorm BPM Release 7.6 You can make role assignments for this user and update their user details, as required. 4. Repeat steps 1 to 3 until you have added all the users you require 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. The user is added to the drop-down list of registered users, and the number of registered users is updated in the status bar. 2. Make role assignments and update the user s details, as required Setting User Details through the User Tab The Details button enables you to set up various details for users to support 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 address in the Address field. This value can then be referenced by a process designer to send to the user. 34 May 2008 Metastorm Inc., 2008

43 Administration Guide 3. Select the Deliver alerts via check box if this user should be sent every alert via the system,. 4. Enter the Distinguished Name and Directory tree where this user s data can be found. These fields support integration with external directory services. 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. 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. Click on the OK button. 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 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. Metastorm BPM Release 7.6 May

44 Metastorm BPM Release 7.6 A list of the roles assigned to that user (if any) in the Roles held field, is displayed. Figure 40: Viewing Role Assignments 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. 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. 2. From the Roles available list select the role (or roles) to be granted to this user. 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. 3. Click on the < button to move the selected role or roles to the Roles held field. 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. 4. Repeat steps 1 to 3 for any other users to whom you want to assign roles. 36 May 2008 Metastorm Inc., 2008

45 Administration Guide 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 Metastorm BPM Release 7.6 May

46 Metastorm BPM Release 7.6 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 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 Metastorm Inc., 2008

47 Administration Guide 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 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 Metastorm BPM Release 7.6 May

48 Metastorm BPM Release 7.6 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 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 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. 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. 2. Select as many users as necessary for this role. Figure 44: Granting a Role 40 May 2008 Metastorm Inc., 2008

49 Administration Guide 3. Click the << button to move the users to the selected role 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. Click the >> button to remove the selected users from the list. 3.7 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. Metastorm BPM Release 7.6 May

50 Metastorm BPM Release 7.6 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 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 Metastorm Inc., 2008

51 Administration Guide 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 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. Metastorm BPM Release 7.6 May

52 Metastorm BPM Release 7.6 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. 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. 4. The Attributes tab is updated to display the new custom relationship table you have defined. 44 May 2008 Metastorm Inc., 2008

53 Administration Guide 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. Metastorm BPM Release 7.6 May

54 Metastorm BPM Release 7.6 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 Metastorm Inc., 2008

55 Administration Guide 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 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. Metastorm BPM Release 7.6 May

56 Metastorm BPM Release 7.6 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 Metastorm Inc., 2008

57 Administration Guide 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 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 1. 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 Metastorm BPM Release 7.6 May

58 Metastorm BPM Release 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. 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 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 The User details dialog is displayed for the user you have selected. Figure 59: User Details 2. Enter the user's address in the Address field. You should always enter a fully qualified address of the form user@domain. This value can be referenced by a procedure designer to send to that user. 3. Select the Deliver alerts via check box if this user should be sent every alert via the system. 50 May 2008 Metastorm Inc., 2008

59 Administration Guide 4. Enter the Distinguished Name and Directory tree where this user s data can be found. These fields support integration with external directory services. 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. 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. Metastorm BPM Release 7.6 May

60 Metastorm BPM Release 7.6 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 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. Select the role to be assigned from the drop down list and click the OK button. 52 May 2008 Metastorm Inc., 2008

61 Administration Guide 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 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.) Any roles that are not shared by all members of the list should be assigned individually through the Users or Roles tabs. 4. When you are finished working with the list, close the list or save it to a file, if necessary. Metastorm BPM Release 7.6 May

62 Metastorm BPM Release 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. Click on the Open File button. The Read list from file dialog is displayed. The dialog is the standard Windows navigation dialog. 2. Select the file, and then click on the Open button. The names in the selected file are displayed. You can work with this list as necessary using the options available on this tab. 3. 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 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 through Click on the Grant button. The Grant Role dialog box Is displayed. 54 May 2008 Metastorm Inc., 2008

63 Administration Guide 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 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 through 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. Metastorm BPM Release 7.6 May

64 Metastorm BPM Release 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 Metastorm Inc., 2008

65 Administration Guide 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. Metastorm BPM Release 7.6 May

66 Metastorm BPM Release 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 58 May 2008 Metastorm Inc., 2008

67 Administration Guide 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. Metastorm BPM Release 7.6 May

68 Metastorm BPM Release Managing Tab Figure 69: Managing Tab The Managing tab provides shortcuts to functionality available from other parts of the System Administrator. 60 May 2008 Metastorm Inc., 2008

69 Administration Guide 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. Metastorm BPM Release 7.6 May

70 Metastorm BPM Release 7.6 SQL Pane Results Pane Figure 71: Metastorm Query 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 Function Connect Enables connection to a database by specifying login, password, and DSN. 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 Last Goes down one result in the Results pane. Goes to the last result in the Results pane. 62 May 2008 Metastorm Inc., 2008

71 Administration Guide 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 Print SQL Preview Save Results Print Results Preview Print Results Help Prints the current SQL query. Displays the current SQL query as it would print, without actually printing. Saves the results to file; defaults to an MS Excel file. Displays the current Results pane as it would print, without actually printing. Prints the Results pane. 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 Designing Reports When you access the Print Results Preview dialog, you can design a report by pressing the Design Report button. This option enables you to update: Generic report options. Report colors. Report fonts. Metastorm BPM Release 7.6 May

72 Metastorm BPM Release 7.6 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 Metastorm Inc., 2008

73 Administration Guide 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. Metastorm BPM Release 7.6 May

74 Metastorm BPM Release 7.6 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 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 May 2008 Metastorm Inc., 2008

75 Administration Guide 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 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. Metastorm BPM Release 7.6 May

76 Metastorm BPM Release 7.6 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 Metastorm Inc., 2008

77 Administration Guide 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' 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. Metastorm BPM Release 7.6 May

78 Metastorm BPM Release 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 Metastorm Inc., 2008

79 Administration Guide 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 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: Metastorm BPM Release 7.6 May

80 Metastorm BPM Release 7.6 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 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 Metastorm Inc., 2008

81 Administration Guide 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 Administrator, Flag Raiser conditional actions e-work.eworktransaction.3 Deals with client requests from whatever source Administrator, Client Metastorm BPM Release 7.6 May

82 Metastorm BPM Release 7.6 Component Main purpose Calling account requires at least one of these roles ework.mq.mqmessagebroker.emessagebroker Configures message queuing Administrator integration and sends messages ework.mq.mqmessagebroker.emqlistener Used by message queuing MQ Notifier integration to process messages to the Engine. Metastorm.eServiceDirector Request Broker Client Metastorm.EEngineSupportImpl Manages ECL transactions Client Metastorm.RemoteConfiguration2 Manages configuration of client for ECL transactions Client, Administrator If the Engine (COM+) application is: Table 3: Components List 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. Select the Action menu Properties. 4. Select the Concurrency tab. 5. In the Synchronization Support field, ensure the Required radio button is selected. 6. Click on the OK button Security Refer to the previous section for instructions on how to access the Security tab. COM+ uses roles, which: Define access based on job items. 74 May 2008 Metastorm Inc., 2008

83 Administration Guide 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. Select the Action menu Properties. 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. Metastorm BPM Release 7.6 May

84 Metastorm BPM Release 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 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: A COM+ application file to describe how the Engine components should be organized in the application. This may be useful for troubleshooting. 76 May 2008 Metastorm Inc., 2008

85 Administration Guide 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. Metastorm BPM Release 7.6 May

86 Metastorm BPM Release 7.6 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. This argument is optional. /? Displays a message box summarizing EngineConfig s command-line arguments. This argument is optional. 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 0x e 78 May 2008 Metastorm Inc., 2008

87 Administration Guide 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 0x a 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 (0x ) 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 (0x a) 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 (0x ) This can occur because the: 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 (0x f) This can occur because the account or group specified in the /BindUserToRole: argument is invalid 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 Metastorm BPM Release 7.6 May

88 Metastorm BPM Release 7.6 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 <probing privatepath=.\dotnetbin;.\dotnetlib /> <add key= Threadpool_MinWorkerThreads value= 50 /> Description 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. 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 Metastorm Inc., 2008

89 Administration Guide 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 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 This can occur because the: 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. Metastorm BPM Release 7.6 May

90 Metastorm BPM Release Engine Registry Settings 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 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 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: 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. 82 May 2008 Metastorm Inc., 2008

91 Administration Guide 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 Query Timeout Key: Name: Type: HKLM\SOFTWARE\Metastorm\e-work\Engine\Database QueryTimeout (secs) DWORD The amount of time the database spends on a query before rejecting it. Note that not all OLEDB drivers support QueryTimeout Login Timeout Key: Name: Type: HKLM\SOFTWARE\Metastorm\e-work\Engine\Database LoginTimeout (secs) DWORD The amount of time the Engine waits for a database connection to be established. Note that not all OLEDB drivers support LoginTimeout Force Case-insensitive Authentication Key: Name: Type: HKLM\SOFTWARE\Metastorm\e-work\Engine\Database Force Case-insensitive Authentication 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. Metastorm BPM Release 7.6 May

92 Metastorm BPM Release 7.6 1, the Engine performs case-insensitive authentication Force Case Sensitive Role Evaluation Key: Name: Type: HKLM\Software\Metastorm\e-work\Engine\ Force Case sensitive role evaluation 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 Fire When Changed On Submit Key: Name: Type: HKLM\Software\Metastorm\e-work\Engine\ FireWhenChangedOnSubmit 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 Disable Static Role Resolution Key: Name: Type: HKLM\Software\Metastorm\e-work\Engine\ DisableStaticRoleResolution 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 Metastorm Inc., 2008

93 Administration Guide Max Simultaneous Async Jobs Asynchronous tasks, such as those resulting from calls to the %ScriptAsync, %Print and % 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: Type: HKLM\Software\Metastorm\e-work\Engine\ Max Simultaneous Async Jobs DWORD Install Info This registry key contains a record of information specified by the user and the installation, when Metastorm BPM is installed. Key: Name: Type: HKEY_LOCAL_MACHINE\SOFTWARE\Metastorm\e-work\InstallInfo InstallInfo 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 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: Type: JScriptPrecompileLevel DWORD Set the value to: 0, for no compilation on start-up 1, to compile map assemblies on start-up Metastorm BPM Release 7.6 May

94 Metastorm BPM Release 7.6 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 ( ), map assemblies, procedure assemblies and map and procedure assemblies are compiled on start up 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: Name: Type: HKEY_LOCAL_MACHINE\SOFTWARE\Metastorm\e-work\Engine AllowGuestUserToRaiseFlag DWORD Set the value to: 0, to force flag raisers to provide credentials. 1, to allow flags to be raised without providing credentials Microsoft Workflow Timeout Key: Name: Type: HKLM\Software\Metastorm\e-work\Engine\ MicrosoftWorkflowTimeout (secs) 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 Microsoft Workflow Enabled Key: Name: Type: HKLM\Software\Metastorm\e-work\Engine\ MicrosoftWorkflowEnabled DWORD Set the value to: 86 May 2008 Metastorm Inc., 2008

95 Administration Guide 0, to disable Microsoft Workflow 1, to enable Microsoft Workflow Administrators are encouraged not to amend this setting. 5.4 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: 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( ) : 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. Metastorm BPM Release 7.6 May

96 Metastorm BPM Release 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) 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: 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 88 May 2008 Metastorm Inc., 2008

97 Administration Guide 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 Event Manager Registry Settings The following registry settings can be configured on each engine: Poll Interval (secs) Key: Name: Type: Value: HKEY_LOCAL_MACHINE\SOFTWARE\Metastorm\ e-work\engine\event manager Poll Interval (secs) DWORD 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: Type: Value: HKEY_LOCAL_MACHINE\SOFTWARE\Metastorm\ e-work\engine\event manager Thread count DWORD This can be set values between 1 and 64. Used to specify the number of threads dedicated to the event manager. Metastorm BPM Release 7.6 May

98 Metastorm BPM Release 7.6 Batch size threshold for thread Key: Name: Type: Value: HKEY_LOCAL_MACHINE\SOFTWARE\Metastorm\ e-work\engine\event manager Batch size threshold for thread DWORD 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: Type: Value: HKEY_LOCAL_MACHINE\SOFTWARE\Metastorm\ e-work\engine\event manager Disabled DWORD 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 Metastorm Inc., 2008

99 Administration Guide 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 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. Metastorm BPM Release 7.6 May

100 Metastorm BPM Release Alert Generator Registry Settings The following registry settings can be configured on each engine: Poll Interval (secs) Key: Name: Type: Value: HKEY_LOCAL_MACHINE\SOFTWARE\Metastorm\ e-work\engine\alert Generator Poll Interval (secs) DWORD 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: Type: Value: HKEY_LOCAL_MACHINE\SOFTWARE\Metastorm\ e-work\engine\alert Generator Thread count DWORD This can be set values between 1 and 64. Used to specify the number threads dedicated to the event manager. Batch size threshold for thread Key: Name: Type: Value: HKEY_LOCAL_MACHINE\SOFTWARE\Metastorm\ e-work\engine\alert Generator Batch size threshold for thread DWORD 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). If the Alert Generator is using a single thread, this key is set to May 2008 Metastorm Inc., 2008

101 Administration Guide Disabled Key: Name: Type: Value: HKEY_LOCAL_MACHINE\SOFTWARE\Metastorm\ e-work\engine\alert Generator Disabled DWORD 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 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. Metastorm BPM Release 7.6 May

102 Metastorm BPM Release 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 Metastorm Inc., 2008

103 Administration Guide 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 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 The /qn Argument The /qn argument does not create a Windows user interface, except for an initial progress bar 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 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 Metastorm BPM Release 7.6 May

104 Metastorm BPM Release 7.6 Property ALLUSERS ADDLOCAL EBYPASSLAUNCH CHECKS 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. 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" 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 EHTTPDCOM EPORT EVRHTTPLISTENE R Machine name or IP address (default value the name of the machine installer is run on). Connection method. Possible values are DCOM (default) and HTTP. HTTP port number for the HTTP connection method. The default value is 80. 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 Metastorm Inc., 2008

105 Administration Guide 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 Metastorm BPM Release 7.6 May

106 Metastorm BPM Release 7.6 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 Type Protocols Outlook TP DCOM, HTTP Notify TP DCOM, HTTP Web TP DCOM, HTTP 1, SOAP Web Parts 2.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 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: 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. 98 May 2008 Metastorm Inc., 2008

107 Administration Guide 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= 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 <ServiceList> <PreAuthenticatedRaiseFlag> <HTTPUseSoap> <Service> <Engine> <Transport> <Server> <EndPoint> <HTTPServer> <Port> Description Container tag that holds one or more <Service> tags. This is a reserved tag and should not be changed. Configures the Remote Open protocol used to connect to the Engine s.net interface to use SOAP or binary formatting. Contains all necessary details about one particular Service. The Service is identifiable by the Name and Description attributes. Each Engine has a name attribute (e.g. Marketing 1 ) to distinguish it from other Engines within the service. Method of transport with which to connect to the server. This is held in the Type attribute. DCOM only. Server on which the Engine is located. If the text is left blank, the server is local. SOAP only. The URL to the Engine s web service (TPWebService.asmx) HTTP only. Server on which the HTTP Listener (emessagehandler) is installed. If the text is left blank, the server is local. HTTP only. Port on which the HTTP server is listening; usually 80. Metastorm BPM Release 7.6 May

108 Metastorm BPM Release 7.6 Tag Name <TransactionURL> <ProxyServer> <ProxyPort> <ProxyUser> <ProxyPWD> Second Transport node: HTTP only. Description 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. Proxy server name. Proxy port name. Proxy user name. Proxy password. 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 Metastorm Inc., 2008

109 Administration Guide </Service> Remote High Performance <Service Name="example" Description="Engine via.net TCP/binary"> <Engine Name="Engine1"> <Transport Type="Remoting"> <Server>tcp://[ComputerName]:4001/ECL</Server> </Transport> </Engine> </Service> Remote Open <Service Name="example" Description="Engine via.net HTTP/IIS"> <Engine Name="Engine1"> <Transport Type="Remoting"> <Server> 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. Metastorm BPM Release 7.6 May

110 Metastorm BPM Release 7.6 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 Metastorm Inc., 2008

111 Administration Guide <Transport Type="DCOM"> <Server>PPASCAL</Server> <!-- Machine Name for local or remote machine --> </Transport> <Transport Type="Remoting"> <Server>tcp://PPASCAL:4001/ECL</Server> </Transport> </Engine> </Service> <Service Name="Marketing" Description="Marketing Service"> <Engine Name="Marketing1"> <Transport Type="DCOM"> <Server>MKTG1</Server> <!-- Machine Name for local or remote machine --> </Transport> <Transport Type="Remoting"> <Server>tcp://MKTG1:4001/ECL</Server> </Transport> </Engine> <Engine Name="Marketing2"> <Transport Type="DCOM"> <Server>MKTG2</Server> Metastorm BPM Release 7.6 May

112 Metastorm BPM Release 7.6 <!-- --> </Transport> Machine Name for local or remote machine <Transport Type="Remoting"> <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> TPWebService.asmx</EndPoint> <ProxyServer /> <ProxyPort>80</ProxyPort> <ProxyUser /> <ProxyPWD /> </Transport> <Transport Type="Remoting"> <Server> </Transport> </Engine> </Service> </ServiceList> </ServiceDirectorConfig> 104 May 2008 Metastorm Inc., 2008

113 Administration Guide 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> <Transport Type="DCOM"> <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: \ / : *? " < > Metastorm BPM Release 7.6 May

114 Metastorm BPM Release 7.6 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 F (15 minutes). Table 7: Service registry setting 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 ) 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 Metastorm Inc., 2008

115 Administration Guide 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 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 Windows NT login dialog appears when using web forms This issue may occur on computers running Windows XP or Server 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: Metastorm BPM Release 7.6 May

116 Metastorm BPM Release 7.6 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" Configuring the web server to operate in NTLM mode prevents clients authenticating via Kerberos to this web server 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 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 Metastorm Inc., 2008

117 Administration Guide 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. 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. Metastorm BPM Release 7.6 May

118 Metastorm BPM Release 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. For information on configuring this setting refer to section 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 Metastorm Browser Settings Administration Form web.config 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. 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. 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 Metastorm Inc., 2008

119 Administration Guide 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 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 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> Metastorm BPM Release 7.6 May

120 Metastorm BPM Release 7.6 Where <languagecode2> is a lowercase two-letter code derived from ISO and <country/regioncode2> is an uppercase two-letter code derived from ISO 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 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 Metastorm Inc., 2008

121 Administration Guide 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 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 and <country/regioncode2> is an uppercase two-letter code derived from ISO 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 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). Metastorm BPM Release 7.6 May

122 Metastorm BPM Release 7.6 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 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 Metastorm Inc., 2008

123 Administration Guide 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 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. Metastorm BPM Release 7.6 May

124 Metastorm BPM Release 7.6 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 Metastorm Inc., 2008

125 Administration Guide 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. Metastorm BPM Release 7.6 May

126 Metastorm BPM Release 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 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 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. Depending on the current view, click on either Modify Shared Web Part or Modify My Web Part. 118 May 2008 Metastorm Inc., 2008

127 Administration Guide 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 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: Metastorm BPM Release 7.6 May

128 Metastorm BPM Release 7.6 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 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 path=%path%; C:\Program Files\Microsoft Visual Studio 8\SDK\v2.0\Bin 2. Use resgen.exe to create the.resource file. For example: 120 May 2008 Metastorm Inc., 2008

129 Administration Guide 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 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 Data Type eusername text (100) Metastorm BPM Release 7.6 May

130 Metastorm BPM Release 7.6 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 ' :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 Data Type egroupname text (31) eprocedurename text (31) emapname text (31) eformtype text (1) B[lank] or A[dmin] eactionname text (31) euserpage 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 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 Metastorm Inc., 2008

131 Administration Guide 3. Enable Jaws support by setting the Enable Jaws Support property 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.... Metastorm BPM Release 7.6 May

132 Metastorm BPM Release 7.6 </system.web> <dms provider="metastorm.dms.sharepoint,version= ,culture=neutral,publickeyt oken=0fa3cc64eebf4c8b" type="metastorm.dms.sharepoint.spdmsprovider"/> </configuration> The DMS provider is defined at the end of web.config 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 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 Metastorm Inc., 2008

133 Administration Guide 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: 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 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 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 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. Metastorm BPM Release 7.6 May

134 Metastorm BPM Release 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 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 Metastorm Inc., 2008

135 Administration Guide 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 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 Publishing Custom List Admin Procedure. Metastorm BPM Release 7.6 May

136 Metastorm BPM Release 7.6 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: Tables ealert, Flight Rows (ealert.efolderid=flight.efolderid) AND (ealert.ealerttype=' ') AND (ealert.eusername='%user.name') 6. Select the Do this tab in the Administration Form s Properties window. 128 May 2008 Metastorm Inc., 2008

137 Administration Guide 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 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 Metastorm BPM Release 7.6 May

138 Metastorm BPM Release 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 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 Publishing Custom List Admin Procedure. 130 May 2008 Metastorm Inc., 2008

139 Administration Guide 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 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. Metastorm BPM Release 7.6 May

140 Metastorm BPM Release 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 Metastorm Inc., 2008

141 Administration Guide Once a connection has been made to the database, a default authentication process is automatically created by the System Administrator. 2. 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 eremdetails erempwddetails Universal Clients only (i.e. not Web Client) Universal Clients only (i.e. not Web Client) 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. Metastorm BPM will remember the last used user name for the service and automatically populate the User Name field Fulfils the functions of both the erempwd and eremdetails scripts Metastorm BPM Release 7.6 May

142 Metastorm BPM Release 7.6 SAP Script Clients Supported Description eguest Web Client 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. Note that InstallOA.js is not a SAP script. Table 9: SAP scripts that ship with Metastorm BPM 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. In the System Administrator, right-click on the Metastorm Authentication MMC snap-in, and select the Connect option. 134 May 2008 Metastorm Inc., 2008

143 Administration Guide 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. Metastorm BPM Release 7.6 May

144 Metastorm BPM Release 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 Metastorm Inc., 2008

145 Administration Guide 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. Metastorm BPM Release 7.6 May

146 Metastorm BPM Release 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 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 Metastorm Inc., 2008

147 Administration Guide 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 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 Name Values \SOFTWARE\Metastorm\e-work \Engine\Database Connectors Current SQL Server DBC Oracle DBC SQL Server DBC Key Name Values \SOFTWARE\Metastorm\ework\Engine\Database Connectors\SQL Server DBC \SOFTWARE\Metastorm\ework\Engine\Database Connection DotNetConnection DotNetProvider Connection Provider=SQLOLEDB; Data Source=[DBServerName]; Initial Catalog=[DBName]; User ID=[DBUserName]; Password=[DBUserPassword]; If DB Authentication is set to NT Authentication, Provider=SQLOLEDB; Data Source=[DBServerName]; Initial Catalog=[DBName]; UserID=[DBUserName]; Password=[DBUserPassword]; Trusted_Connection=Yes; Data Source=[DBServerName]; Initial Catalog=[DBName]; User ID=[DBUserName]; Password=[DBUserPassword]; Connection Timeout=[DBConnectionTimeoutInSeconds]; If DB Authentication is set to NT Authentication, Source=[DBServerName]; Initial Catalog=[DBName]; User ID=; Password=; Trusted_Connection=Yes; Connection Timeout=[DBConnectionTimeoutInSeconds]; System.Data.SqlClient ODBC; DSN=Metastorm; UID=[DBUserName]; PWD=[DBUserPassword]; Metastorm BPM Release 7.6 May

148 Metastorm BPM Release 7.6 Oracle DBC Key Name Values \SOFTWARE\Metastorm\ework\Engine\Database Connectors\Oracle DBC \SOFTWARE\Metastorm\ework\Engine\Database Connection DotNetConnection DotNetProvider Connection Provider=OraOLEDB.Oracle.1; Data Source=[DBOracleServiceName]; User Id=[DBUserName]; Password=[DBUserPassword]; FetchSize=100; CacheType=Memory; PLSQLRSet=1 Data Source=[DBOracleServiceName]; User Id=[DBUserName]; Password=[DBUserPassword]; FetchSize=100; Cache Type=Memory; PLSQLRSet=1; Connection Timeout=[DBConnectionTimeoutInSeconds]; Oracle.DataAccess 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 Metastorm Inc., 2008

149 Administration Guide Engine Mail Connectors Mail Connector registry parameters are used to set up the Process Engine to work with . Key Name Values Engine Name Connector For SMTP: ProgID=ework. MailConnector.[MailConnectorType (SMTP)] ; DefaultAddress=[ Address]; 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 % 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 s and all %SendMail calls are ignored. % defines the Unicode format to be used for all content. Setting Locale id =1252 represents the western European character set. For other character sets refer to Unicode definitions, e.g is used for eastern European languages and (UTF-8) is suitable for the Russian and Kanji character sets. To avoid clashes in a multi-engine environment, every Engine must have a unique name. Key Name Values Name [Name (Domain$MachineName)] Engine Browser Protocol This setting allows the Engine to construct links to folders when sending alerts via . Key Name Values \SOFTWARE\Metastorm\ework\Engine\MailConnector \SOFTWARE\Metastorm\ework\Engine \SOFTWARE\Metastorm\ework\Engine Browserprotocol web.dll/ For further details, refer to the Installation Guide. Metastorm BPM Release 7.6 May

150 Metastorm BPM Release HKEY_CURRENT_USER Clients List Provider The parameter specifies the machine from which the Clients receive information about available Process Engine services. Key Name Values \Software\Metastorm\e-work\Win32 Clients\Shared\EClientMgr \Software\Metastorm\e-work\Win32 Clients\Shared\EClientMgr List Provider Connection Method 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. Set to 1 for DCOM, or 2 for HTTP. \Software\Metastorm\e-work\Win32 Clients\Shared\EClientMgr \Software\Metastorm\e-work\Win32 Clients\Shared\EClientMgr URL Port The virtual directory used to access the service list (only required for HTTP connections) e.g. /escripts The port used to access the service list (only required for HTTP connections) 9.2 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 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: the Computer Management tool 142 May 2008 Metastorm Inc., 2008

151 Administration Guide COM+ Metastorm Engine Roles For further details, refer to the Engine section of this document 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 Values Enable Public Attachment 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 Values Auto Refresh Alert Lists 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 Browser Settings Administration Form of this document and the Using Metastorm BPM with Internet Explorer guide. Metastorm BPM Release 7.6 May

152 Metastorm BPM Release 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 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 Metastorm Inc., 2008

153 Administration Guide 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" /> <threshold value="7" /> </thresholds> <refreshinterval value="5" locked="0" /> <weburl value=" locked="0" /> <process value="" locked="0" /> <branding value="1" locked="0" /> <sound value="1" locked="0" /> </settings> Locking a Setting To lock a setting, set locked="1" 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=" locked="0" /> The default value: <weburl value=" locked="0" /> Metastorm BPM Release 7.6 May

154 Metastorm BPM Release 7.6 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 Metastorm Inc., 2008

155 Administration Guide 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: One Range <thresholds locked="0"> <threshold value="4" /> <threshold value="7" /> </thresholds> To display all priorities, use the following syntax: <thresholds locked="1"> </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 locked="0"> <threshold value="4" /> </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 locked="0"> <threshold value="4" /> <threshold value="7" /> </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. Metastorm BPM Release 7.6 May

156 Metastorm BPM Release 7.6 Figure 90: Priority Ranges tab 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 Metastorm Inc., 2008

157 Administration Guide Refresh The Metastorm Notify Gadget can be set to a value of 1 to 60 minutes. The default value is 5 minutes. Branding <refreshinterval value="5" locked="0" /> 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 <branding value="1" locked="0" /> <branding value="0" locked="0" /> 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". Metastorm BPM Release 7.6 May

158 Metastorm BPM Release 7.6 Figure 93: Other tab 150 May 2008 Metastorm Inc., 2008

159 Administration Guide 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, where you can download them for your own use. If you develop a procedure that you want to share with other users, please 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: Standard Library Name Description Libraries Used Reporting Library BizTalk Data Services Library Provides a standard Audit Trail form used by other Administrative - procedures (and available for use in any other procedure). Provides client script functions used to generate charts and export - comma-separated-values from the contents of a report grid. Provides functions used with Metastorm BizTalk Data Services. - MQ Library Provides functions used for Message Queue integration. - Browser Settings Provides client script functions for loading and saving user settings to - Library 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 Metastorm BPM Release 7.6 May

160 Metastorm BPM Release 7.6 Name Description Libraries Used Business Activity Monitoring Designer Log eb2b KPI Dashboards List Maintenance Line of Business Reporting MQ Administration (uses the MQ Library) Purge Query Service Monitor Update Time-out User Profiling A set of Administrative Forms for monitoring the state of any process. A pair of Administrative Forms for reviewing the Process Designer and Authentication logs. A procedure shipped with the EAI Adaptor for Microsoft BizTalk, which allows a register of trading partners to be established. A set of Administrative Forms that allow the display of metrics relating to processes. An Administrative Form for moving and copying To Do and Watch list entries between users. A procedure which provides an Administration Form (Report Definition) for defining a custom Line of Business report. A set of Administrative Forms for registering and unregistering message queues. A map for setting up a scheduled purge of defunct folders and sessions, along with an Administrative Form for performing the purge on demand. 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). A map for performing a monthly check on Metastorm license usage. Reports and charts of historical usage may be produced. An Administration Form for setting the session time-out period for users accessing Clients. 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. Table 10: Administrative Procedures List Reporting Standard - Standard; Reporting - Standard 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 Metastorm Inc., 2008

161 Administration Guide 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. Metastorm BPM Release 7.6 May

162 Metastorm BPM Release 7.6 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 Metastorm Inc., 2008

163 Administration Guide 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 Metastorm BPM Release 7.6 May

164 Metastorm BPM Release 7.6 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 Metastorm Inc., 2008