MBPM Designer User's Guide

MBPM Designer User's Guide Release 9.2.1 This documentation has been created for software version 9.2.1. It is also valid for subsequent software versions as long as no new document version is shipped with the product or is published at https://knowledge.opentext.com. Open Text SA 40 Avenue Monterey, Luxembourg, Luxembourg L-2163 Tel: 35 2 264566 1 Open Text Corporation 275 Frank Tompa Drive, Waterloo, Ontario, Canada, N2L 0A1 Tel: +1-519-888-7111 Toll Free Canada/USA: 1-800-499-6544 International: +800-4996-5440 Fax: +1-519-888-0677 Email: support@opentext.com FTP: ftp://ftp.opentext.com For more information, visit www.opentext.com. Copyright © 1996–2012 Open Text Corporation OpenText is a trademark or registered trademark of Open Text SA and/or Open Text ULC. The list of trademarks is not exhaustive of other trademarks, registered trademarks, product names, company names, brands and service names mentioned herein are property of Open Text SA or other respective owners. Disclaimer No Warranties and Limitation of Liability Every effort has been made to ensure the accuracy of the features and techniques presented in this publication. However, Open Text Corporation and its affiliates accept no responsibility and offer no warranty whether expressed or implied, for the accuracy of this publication. Table of Contents Chapter 1 MBPMComponents 18 Chapter 2 Solution, Project and Process 19 Solution 19 Project 19 Process 20 Chapter 3 Stage and Action 21 Stage 21 Action 21 Chapter 4 Navigation 23 Chapter 5 Toolboxes 25 Sorting the Toolbox contents 25 Chapter 6 Repository 27 Chapter 7 Inventory 29 "Used by” Item 29 Chapter 8 Templates 31 Create a template 31 Configure Template Locations 31 Creating a New Component Using a Template Chapter 9 Importing and Exporting 32 33 Importing Components 33 Exporting 33 Exporting Components 33 Exporting Graphics 34 Importing and Exporting Language Files 34 Importing 34 Exporting 35 1 Chapter 10 Setting the Designer Options 37 Chapter 11 Designing a Project 41 Define the Initial Action 41 Define and Prioritize Tasks 41 Identify Participants 42 Determine Necessary Information 42 Determine Possible Outcomes 42 Identify Reusable Elements 42 Maintain the Process 42 Chapter 12 Creating a Project Setting the Project Properties 43 Process Overview 43 Elements of a Process 44 The Process Toolbox 44 Docking and Pinning 44 Docking 44 Pinning 45 Lanes 45 Adding a Lane 45 Editing Lane Properties 46 Moving Lanes 46 Adding a Stage to a Lane 46 Moving a Stage from one lane to another 46 Deleting a Lane 47 Creating a Process 47 Create a Process 47 Process Element Properties 2 43 47 Archive stage 48 Comment 48 Common stage 49 Conditional action 50 Flag action 51 Group stage 52 Linked process stage 53 Process 54 Rendezvous action 55 Rules stage 56 Start stage 57 Sub-Process 58 Sub-Process stage 58 System stage 59 Timed action 60 User action 61 User stage 63 Chapter 13 Introduction to Sub-Processes 65 Sub-Process Rules 66 Sub-Process Properties 66 Creating Sub-Processes 66 Adding a Sub-Process to a Process 66 Using Sub-Processes 66 Nested Sub-Processes 67 Chapter 14 Introduction to Linked Processes 69 Linking Processes 70 Nested Linked Processes 71 Chapter 15 Working with Processes 73 Adding Stages to a Process 73 Defining the Process Stage Order 73 Set the Stage Order 73 Adding Actions to a Process 73 Add a Direct Action 74 Add a Loopback Action 74 Changing the Action Style 74 Icons and Event Handlers 74 Icons 74 Event Handler 74 Adding Comments to a Process 75 Comment Action Rules 75 Add a Comment 75 3 Change the Comment Shape and Content Style Change Style of Comment Contents 75 Selecting Process Elements 76 Copying Process Elements 76 Deleting Process Elements 77 Changing Fonts and Colors of Process Elements 77 Chapter 16 Stage Types Clapperboard (Start Stage) Clapperboard Rules User Stage User Stage-Action Rules Group Stage Group Stage Action Rules Sub-Process Stage Sub Process Stage Action Rules Linked Process Stage Linked Stage Action Rules Rule Stage Rule stage Action Rules System Stage System Stage Action Rules Common Stage Common Stage Action Rules Archive Stage Archive Stage Action Rules Deleting a Stage Chapter 17 Action Types 79 81 81 81 81 81 81 81 82 82 82 82 82 83 83 83 83 83 83 83 85 Loopback Actions 86 User Action 86 User Action Rules Timed Action Timed Action Rules Conditional Action Conditional Action Rules 4 75 87 87 87 87 87 Rendezvous Action Rendezvous Action Rules Flag Action Flag Action Rules Loopback Action Add a Loopback Action Chapter 18 Introduction to Folders 88 88 88 88 88 88 91 Folder ID 91 Folder Name 91 Cloning Folders 91 Chapter 19 Introduction to Libraries 93 Creating a Library 94 Adding Items to Library 94 Associating Library with a Process 94 Associating Library with a Process of another Solution 95 Chapter 20 Designing a Form 97 Guidelines 97 Creating a Form 97 Create a New Form 98 Using the Form Toolbox 98 Using Forms and Form Segments 99 Open an Existing Form or Form Segment 99 Close a Form or Form Segment 99 Editing Form and Form Segment Properties 99 Form Component 100 Form Segment Component 101 Form Controls 102 Using Form Controls 104 Moving Controls 104 Moving a Single Control 104 Moving Multiple Controls 105 Copying and Pasting Controls 105 Aligning and Spacing Controls 105 Aligning Individual Controls 106 5 Aligning and Spacing Groups of Controls 106 Removing Controls 106 Grid controls 106 Forms on Web Client 106 Tab Order and Tab Index 107 Changes in MBPM v9.2 SR1 107 Editing Form Control Properties 108 Attachment clip 108 Checkbox 110 Command Button 112 Currency 115 Date/Time 119 Dropdown 122 Grid 126 Image 137 Label 139 Using dynamic URL for Label 140 List 141 Memo 144 Multi-clip 147 Number 148 Panel 152 Person 153 Rich Text 155 Radio group 159 Rule 162 Signature 163 Status 165 Text 170 Using a text field to add a hyperlink 174 Chapter 21 Introduction to Form Segments 6 177 Creating and Using Form Segments 178 Adding Controls to a Form Segment 178 Adding an instance of Form Segment to a Form 178 Chapter 22 Introduction to Administration Forms 181 Creating Administration Forms 181 Chapter 23 Admin Form Group 183 Moving Admin Forms among Admin Form Groups 183 Deleting Admin Form Groups 183 Chapter 24 Introduction to Roles 185 Defining a Role 185 Creating a Role 185 Group Role 186 Dynamic Role 186 Chapter 25 Introduction to Find and Replace 189 Find Text 189 Advanced Find and Replace 189 Find Results 190 Replace Text 190 Filtering the Results 190 Chapter 26 Introduction to Business Objects Types of Business Objects Custom Business Objects 191 191 193 Data Access 193 Process Context Business Objects 193 Cost and Revenue Enhancements 197 Process Business Objects 199 Local Business Objects 199 Add a Variable to a Local Business Object 200 Delete a Variable from a Local Business Object 200 Binding Processes to Forms and Reports 200 Adding a Business Object to a Component Twice 202 Binding to Custom Variables 202 Binding to Process Context Variables 203 Introduction to Custom Business Objects 203 Database Custom Business Objects 203 Table Business Object 204 Query Business Objects 204 7 LDAP query 205 Creating a Connection 206 Web Service Connection 207 Creating Custom Business Objects 209 Defining Custom Business Object Parameters 210 Introduction to Database Business Objects Error message 211 Defining Table and Query Business Object Parameters 212 DMS Business Objects for Content Server 214 Introduction to Scripted Business Objects 214 Developing a Scripted Business Object Server Script 214 The Anatomy of a Scripted Business Object 215 Business Object Implementation Types 226 Creating Scripted Business Objects 233 Defining Scripted Business Objects Parameters and Scripts 234 Implementing a Scripted Business Object for a Grid Control 234 Troubleshooting 234 MSDTC Configuration 235 Chapter 27 Query Builder 237 Building a single query Adding objects to the query 238 238 Setting object aliases 239 Joining tables 239 Adding and removing joins 239 Changing join type 240 Selecting output fields 241 Working with expressions in the Columns Pane 8 211 242 Sorting a dataset 243 Defining criteria 243 Grouping output fields 244 Building a query with sub-queries 244 Navigating the query tree 244 Working with sub queries 245 Working with derived tables 246 Working with unions 248 Union Sub-Query operations 248 Operations with brackets 248 Chapter 28 Filter Editor 249 Remarks 249 Add Conditions 250 Delete Conditions 250 Work with Clipboard 251 Change a Column in a Filter Condition 251 Change an Operator in a Filter Condition 251 Edit a Condition's Value 251 Compare a Condition's Column with Another Column 251 Navigation 252 Filter Criteria with Multiple Logical Operators 252 Chapter 29 Introduction to Visual Scripts 253 Interface 253 Types of Visual Scripts 254 Event Handler Buttons Event Handler Visual Scripts Creating a new event handler Visual Script Reusable Visual Scripts Creating a new reusable Visual Script 254 254 255 255 255 Categorizing a Promoted Reusable Visual Script 255 Creating Event Handler Visual Script 256 Enhanced View 256 Properties pane of process 257 Deleting an Event Handler Visual Script 257 Visual Script Toolbox 257 Commands 257 Visual Scripts 270 Document 276 Database Category 283 Using Standard Activities 292 Transactional Support 293 9 Chapter 30 Introduction to Expression Builder Building Expressions using Intellisense OK, Cancel and ESC 10 295 297 297 Building Formulas using the Expression Builder 298 Expression Builder Formulas 298 AbsoluteNumber 299 AllNotes 299 AND 299 CalculateDateTime 299 CalculateDuration 300 ConcatenateSubstrings 301 CountCharacters 301 DeleteAttachment 301 ExecuteStoredProcedure 302 ExtractSubstring 302 Findsubstring 302 FormatDateTime 303 GetEarlierMessage 304 GetEarlierNote 304 GetEmailAddress 305 GetEmailAddresses 305 GetToDoList 305 GetUserAttribute 305 GetUserDistinguishedName 305 GetWatchList 306 HtmlToText 306 IF 306 Left 307 List 307 ListPublishedRoles 307 ListRegisteredUsers 307 ListSelectedUsers 307 MaximumNumber 308 MinimumNumber 308 NOT 308 Never 308 NewAttachment 308 OR 309 Pair 309 ReadAttachment 309 ReadFile 309 Remainder 310 ReplaceSubstrings 310 Right 310 RoundNumber 310 SaveAttachment 311 SearchDirectory 311 SelectSQL 311 UsersManager 312 UsersStaff 312 GetColumns 312 Using List Functions Library 313 Function 313 Data Types 314 Casting 316 Implicit Typecasts 317 Using Operators 319 Modes of Expression Builder 320 Text and Memo mode 320 Assignment mode 321 Adding an Assignment 321 Editing an Assignment 322 Deleting an Assignment 322 Condition mode 323 Adding Conditions 323 Editing a Condition 323 Deleting a Condition 323 SQL Mode 324 11 Constructing a simple Select statement 324 SelectSql Properties 325 Constructing a Parameterized Select statement 325 List Mode 326 Using Check Mode 327 Using AND 327 Using ‘OR’ 328 Using ‘NOT’ 328 Using ‘IF’ 329 Chapter 31 Introduction to Scripting C# Guidelines 331 Server-Side Scripting 332 Using Business Objects 332 Passing Business Objects to Scripts 332 Writing Functions that use Business Objects 333 Passing a Business Object Instance to a Function 333 Passing Form Local and Process Business Objects 334 Passing a Form or Process Context 335 Process Runtime API Reference 335 Using the Business Object’s Refresh Method 336 Access selected row of Grid 336 Using the Business Object in Server Script 336 Reading Variable values 336 Setting Variable values 337 Reading a DataSet 337 Writing a DataSet 337 Controlling the Parameters of a Business Object 337 Promote Reusable Server-side scripts 339 Promotion Attributes 340 Client-Side Scripting 342 SetField Syntax 343 GetField Syntax 346 Grid Functions getCurrentRow 12 331 349 349 getCurrentCol 349 getRowCount 349 getCell 349 setCell 350 showSubmit and showCancel Functions 350 showSubmit 350 showCancel 350 submitForm, cancelForm and buttonClick Functions Chapter 32 Introduction to Flags 350 353 Creating a Flag 353 Raising a Flag 354 Using eraiseflag.exe to raise a flag from an external application Receiving Flag Data Associating Flag Data to a Business Object Chapter 33 Introduction to Reports 355 356 357 359 Creating a Report 359 Reports Interface 359 Adding new bands Report Group 360 361 Moving Reports among Report Groups 361 Deleting Report Groups 361 Reports Toolbox 361 Report Bands 361 Report Controls 363 Report controls and their properties 364 Bottom margin band 364 Checkbox 365 Detail band 366 Grid 367 Grid Cell 371 Grid Row 372 Grid footer band 372 Grid header band 373 Hyperlink 374 13 Image 379 Label 380 Memo 381 Native Report 382 Page break 384 Page footer band 384 Page header band 385 Page Info 386 Panel 387 Report Filter Area 387 Report footer band 389 Report header band 389 Shape 390 Top margin band 391 Filter Controls 392 Filter controls and their properties 392 Checkbox 392 Command button 394 Date/Time 396 Dropdown 398 Image 400 Label 401 Memo 402 Number 404 Rule 406 Text 407 Custom Lists Creating a Custom List Chapter 34 Using Charts in Reports 14 409 409 413 Chart Design Context Ribbon 413 Chart Composition 413 Setting Chart Appearance 414 Series 414 Arrange Series 414 Type 415 Styles 415 Palette 415 Define Custom Palettes 415 Editing Default Palettes 415 Variations 416 Elements 417 Chart title 417 Legend 417 Point Options 417 Argument 417 Values 417 Labels 417 Markers 417 Axes 417 Grid Lines 417 Selecting Chart Types 418 Bars 418 Points and Lines 419 Pie 420 Areas 420 Chart controls and their properties 421 Chart 421 Chart Axis 422 Chart Pane 422 Chart Series 423 Chart Series (Common) 424 Chart Series (Pie Chart) 425 Chart Series (XY Chart) 425 Diagram (XY 3D) 425 Chapter 35 Introduction to Multi-Lingual Processes 427 Setting the Project Languages 429 Creating the Translations 429 Translate via the Translation Pane 430 15 Translate via the Properties Pane Designing Localization Layouts Repositioning Controls on Forms Chapter 36 Introduction to Solution Tables 431 431 433 Create a Solution Table 433 Identity Columns 434 Chapter 37 Deploying a Project, Library or Solution 435 Chapter 38 Debugging 437 Debugging a process 437 Debugging without administrative privileges 437 Setting Breakpoints in C# Code Troubleshooting Checklist Debugging in Windows XP Chapter 39 Troubleshooting 438 439 439 439 441 Code Generation Error Troubleshooting 441 Deployment Internal Error 441 Chapter 40 Process Activator 443 Introduction to Process Activator 443 Activated Process as a Web Service 446 Activating the Sample Process 446 Allow Activated Process Web Service Access through SSO Chapter 41 Document Management System 448 451 Setup 451 DMS Features 451 DMS Controls 451 DMS Single Attachment Clip 452 DMS Multiple Attachment Clip 452 DMS Properties 452 Introduction to DMS Business Objects for Content Server 16 430 453 Creating a Content Server DMS Connection 453 Creating DMS Business Objects 454 DMS Business Objects Attributes and Variables 454 Navigating the Attributes Tree 455 System Attributes 455 Attribute Data Types 456 Assigning Variable Names to Attributes 456 Using Content Server Business Objects on Forms Opening Content Server Attachment 456 457 DMS Libraries and Functions 457 DMS Functions 457 Get Document Id 458 Get Folder Document Ids 458 SharePoint Functions 458 Content Server Functions 463 Content Server DMS Provider Activities 469 Chapter 42 Accessiblity Designing an accessible process 477 477 Section 508 477 Keyboard navigation 477 Internet Explorer Text Size 477 JAWS Support 478 Chapter 43 MBPM Reserved Words 481 Chapter 44 OpenText Mobile BPM 483 Supported Form Controls in Mobile Client 483 Unsupported Features and Form Controls in Mobile Client 483 Field Behavior 484 Alignment 485 Action Description and Help URL 485 Command Button 486 Attachment Clip 487 Multi Clip 488 Status 488 GPS 488 17 Chapter 1 MBPMComponents MBPM™ is composed of the following components: l An MBPM database l One or more MBPM Process Engines l A Service List l A Deployment Service l MBPM Web Extensions l Web Client 18 Chapter 2 Solution, Project and Process Chapter 2 Solution, Project and Process Solution An MBPM Solution consists of a set of projects. A Project (previously called a Procedure in MBPM v7.6) holds one or more processes. Each process is a collection of forms, actions, stages, and so on. The Solution, Project, and Process hierarchy is displayed below: Note: You can save the entire solution using the MBPM button > Save. Project In MBPM, a Project is a collection of one or more processes. MBPM Designer User's Guide 19 Chapter 2 Solution, Project and Process Process An MBPM Business Process is any sequence of actions that you wish to automate. A business process may be as simple as approving an employee’s expenses request, or as complex as a support system that tracks all support activity from the initial support call to its final resolution. A process is a graphic representation of the business process and may also contain (or use) any number of forms, form segments, roles, visual scripts, and so on. 20 MBPM Designer User's Guide Chapter 3 Stage and Action Chapter 3 Stage and Action When you design a process, it is represented through one or more process diagrams, each illustrating the various steps required to complete a specific business process (the life cycle of a folder). Each instance of the business process is called a folder. Folders are progressed in steps referred to as stages. At each stage, actions such as recording information are performed on the contents of the folder. Stage A stage is a stopping point in a process. Upon reaching a stage, a folder may require a user to act upon it or it may be acted upon by the system, either by querying existing data in the folder or by adding data. When a folder arrives at a stage, other than a system stage, it is made available for examination or action to selected process users through the client interface. Action Action represents the activity that happens to a folder as it progresses through a process. Actions can loop back to the same stage or can link stages, which would cause the folder to move from one stage to the next. Actions may include activities such as: l Filling out a form l Logging a telephone call l Reviewing an attached file l Approving or denying a request In MBPM, it is also possible to have actions that do not require human intervention, such as: l Determining the routing for a folder based on information available in a folder or in a database. l Raising or responding to an event l Moving a folder after a timed action l Starting an external application You can set properties and formulas in the MBPM Designer to accommodate a wide variety of possible actions. MBPM Designer User's Guide 21 22 MBPM Designer User's Guide Chapter 4 Navigation Chapter 4 Navigation The Navigation Pane consists of Inventory, Properties, Toolbox, Repository, and Data Access toolbar buttons that are stacked to the left of the Designer window. Clicking on a button will launch the appropriate toolbar. You can control the number of buttons displayed either by clicking on the drop-down below the Data Access button or by re-sizing the Navigation Pane to display the desired buttons. You can choose between Navigation Pane mode and Multiple Task Pane modes from Options > Display > Task Panes tab. For more information, refer to Setting the Designer Options. MBPM Designer User's Guide 23 24 MBPM Designer User's Guide Chapter 5 Toolboxes Chapter 5 Toolboxes The Designer uses a number of toolboxes. The toolboxes share the same pane, on the left side of the Designer pane. Only one of these toolboxes is available at a time: l When a process is active in the main pane, the Process Toolbox is displayed. l When a form is active in the main pane, the Form Toolbox is displayed. l When a report is active in the main pane, the Report Toolbox is displayed. l When a visual script is active in the main pane, the Activity Toolbox is displayed. You may choose to customize your Designer display by moving the toolboxes to a more convenient location. Regardless of their location, each toolbox will appear only when you are working with the corresponding component. You use the buttons on the toolboxes to add controls to processes, forms, reports and so on in a process. To toggle the Toolbox pane on and off: Select the View tab and click on the Toolbox button. The appropriate toolbox for the active component is displayed. Sorting the Toolbox contents You can right-click in the Toolbox to do one of the following: l Sort alphabetically l Reset order For example, with a process in the main pane of Designer, the sections in Process Toolbox are Default, Stages, Actions, Miscellaneous, Roles, and Business Objects. Any new Business Objects created are appended to the end of the Business Objects section with the most recently created Business Object at the bottom of the section. If you right-click in the Toolbox and select Sort alphabetically, the Default section stays at the top and all the other sections are sorted alphabetically. The items within the sections are also sorted alphabetically. To set it back to the default order, right-click in the Toolbox and select Reset order. MBPM Designer User's Guide 25 26 MBPM Designer User's Guide Chapter 6 Repository Chapter 6 Repository The Repository enables the process designer to view and access the services that are available, for example libraries, remote databases, and so on. The Repository is a floating dialog, which you may move or toggle on/off at your convenience. The Repository is not displayed by default. To toggle the Toolbox on and off: Select the View ribbon tab and click on the Repository button. The Deployment node has a default child node to represent the user’s local storage area which is used for the deployment of off-line libraries. To configure the Deployment Services: 1. In the Repository, right-click Deployment Services > Configure Deployment Services. The Deployment Services page in the BPM Options dialog box is displayed. 2. Choose the path for the deployment services list. The deployment service list file is named DeploymentServiceConfig.xml The path is usually C:\Program Files\Metastorm\BPM\IIS extensions\DeploymentServiceConfig.xml 3. Click Validate. If invalid, a message is displayed. 4. Click OK. MBPM Designer User's Guide 27 28 MBPM Designer User's Guide Chapter 7 Inventory Chapter 7 Inventory The Inventory provides information on the objects in your solution and the logical relation between the objects. For example, it displays forms and their associated actions, scripts and their associated components, and so on. It enables the process designers to see the structure of their solutions and projects more clearly. The Inventory allows you to drill down to components such as stages, actions, and forms. When you double-click on an item in the Inventory, it will be opened in the main pane, or will gain focus if it is already open. You can set the options to display items with a singleclick in the Inventory. For example, if you want to view a form component, find the form in the Inventory and double-click to open it. Form will be opened in the main pane, or will gain focus if it is already open. The Inventory is a pane, which you may move or toggle on/off. To toggle the Inventory on and off: l Select the View ribbon tab and click on the Inventory button. "Used by” Item Components in the Inventory display other components that are using them by using the "Used by" display item. The following components display “Used by” by connecting them to relevant items: l Form ->Used by-> Stages and Actions l Roles->Used by ->Stages, Actions, Forms, Reports, and Admin forms l Process->Used by->Process l Sub-Process->Used by->Process l Flag-> Used by->Action l Form Segment-> Used by->Forms l Business Objects->Used by->Processes, Forms, Reports, and Custom Lists MBPM Designer User's Guide 29 30 MBPM Designer User's Guide Chapter 8 Templates Chapter 8 Templates A template is a placeholder for default values, layout and controls. In MBPM Designer, forms and reports serve as containers for other items and therefore qualify to be saved as templates. For example, a form can define a company’s default style in terms of fonts, colors, values, layout, controls, and so on. This form when saved as a template can be re-used in the same project or a different project to create new components that inherit the template’s design. Components that are created from a template do not maintain a link with the template. This means that if a template is updated, components that have already been created using the template do not reflect the updates. If you want to create a new component that is updated automatically whenever the template is updated, creating a form segment is more suitable than creating a template. Templates, when saved, will not include languages. When you create a form or form segment, and then save it as a template, if it has multiple languages set up, the non-default languages do not come across in the template. Create a template 1. Select the Form or Report tab in MBPM Designer. 2. Click the MBPM button > Export > Template. 3. Type a name and click Save. The file is saved in My Metastorm Templates folder. Configure Template Locations 1. Click the MBPM button. 2. Click Options . 3. Select Templates. 4. Click Add to add a new location or click Edit to change the default location for saving templates. 5. Click Remove to remove a location that you no longer want to use as the default template folder location. Remove is available only when you have more than one folder location listed under Template options. MBPM Designer User's Guide 31 Chapter 8 Templates Clicking Add or Edit displays the Browse for Folder dialog box. 6. Select a folder and click OK. Depending on your choice of Add or Edit, the folder location is either added or updated to reflect the new selection. Creating a New Component Using a Template 1. In the Home tab of the Designer, click on the drop-down button in the Components ribbon tab. 2. Scroll down to the end of the list of components to view your saved templates. 3. Click on the chosen template. An instance of the template is added to the active project. 32 MBPM Designer User's Guide Chapter 9 Importing and Exporting Chapter 9 Importing and Exporting The import and export features allow you to store and retrieve individual components within your solution. Importing Components You can import all the components that have been exported. To import a component: 1. Click the MBPM button > Import. 2. From the Files of type drop-down, select the component that you want to import. The exported components of the selected component type are displayed. 3. Click the component that you would like to import and click Open. You can now view the imported component in a new tab within the main pane of the Designer. Exporting You can export a component, graphic, or template. Exporting Components You can export the following components: l Connection l Solution Table l Flag l Role l Business Object l Process l Sub-Process l Admin form l Report l Form l Form Segment MBPM Designer User's Guide 33 Chapter 9 Importing and Exporting To export a component: 1. Click on the relevant component tab in the main pane of the Designer. 2. Click the MBPM button > Export > Component. 3. Type in a file name. 4. Click Save. The component is exported as a package file. Exporting Graphics You can save a screenshot of a component by using the export as graphic feature. To export a graphic: 1. Click on the relevant component tab in the main pane of the Designer. 2. Click the MBPM button > Export > Graphic. 3. Type in a file name. 4. Click Save. You can now view the exported graphic files in .PNG format at the saved location. Importing and Exporting Language Files The Import/Export Language Files feature allows you to retrieve translation (.resx) files with all of the appropriate strings already populated (by the translation agents or services). This avoids having to manually enter in values for every string and for every language. Importing 1. Click the MBPM button > Import > Import Language Files. 2. From the Browse dialog, choose a folder where the language files for import are located. 3. After selecting the source folder, the Import feature detects the languages stored in the selected folder. 4. A “Choose Languages” dialog is displayed listing the languages that can be imported into the current project. 5. An Overwrite option, displayed for each detected language, provides the possibility to overwrite all of the existing translations for a given language. 6. When a language is imported which does not currently exist, it will be added to the translation pane and project properties for the active Project/Library. 7. Click on OK to start the Import process. Note: Adding and replacing resx (Translation) files reflects a change to the project and is marked as such. All changes should therefore be saved before using the Import Language Files feature. 8. The Progress of the Import Language Files process is indicated with a progress bar and file-by-file information messages appearing in the message pane, along with a icon that 34 MBPM Designer User's Guide Chapter 9 Importing and Exporting blinks in the status bar. Exporting 1. Before language files can be exported, it is necessary to add at least one language to the currently opened project. This is achieved by double-clicking on the project and setting the available language. Note: Once the language is added, the Project must be saved in order for the Export Language Files menu option to be enabled. Until this is done, the Export Language Files menu option under Export will be disabled (grayed out). 2. Click the MBPM button and then select Export -> Export Language Files. 3. A Browse Folder will appear allowing a folder to be specified for the exported files. Alternatively, a new target folder can be created. 4. Click OK on the Browse Folder dialog.. 5. The Export process will commence. Note: This will only be carried out for the currently opened Project/Library’s set of languages. 6. Each of the exported language's localized files will be placed in a separate countrycoded folder with a country-coded file extension. An example of an exported localized file is: Project1.fr.resx. 7. The Progress of the Export process is indicated with a progress bar and file-by-file information messages appearing in the message pane, along with an icon that blinks in the status bar. 8. A final message will appear in the message pane indicating the quantity of exported files. MBPM Designer User's Guide 35 36 MBPM Designer User's Guide Chapter 10 Setting the Designer Options Chapter 10 Setting the Designer Options You can set your preferences for specific view, display, and editing settings in the Options window. To display the options, click the MBPM button > Options. The settings in the options menu are: l Deployment - set the locations to where the project will be deployed. For more information, see Repository. By default, you are warned about over-writing roles and processes. You can also turn on Windows Single sign-on (SSO) whereby authenticating the user one single time permits access to all systems where you have access permission, without the need to enter multiple passwords. Note that this option can only be used if the system is already configured for SSO. The Process Diagnostics Service address field is related to Process Debugging feature. Process Diagnostic service is connected to an MBPM Repository in the same way as the Deployment service with the web.config file containing a connection string to the repository. l l Forms - set the default form background color. For more information, see Creating a Form. Process Modeling - Choose from Basic and Enhanced process model style and the line styles in a process. When you choose Enhanced process model style, besides a different visual style, the stages and actions of your process are displayed with links to create visual scripts. For more information on creating visual scripts, see Visual Scripting Interface. Color Settings: The default font color and border color can be specified for the following items: l Comments l Stages Note that changing a default value will not change any currently set colors. l Default Connection - The MBPM Designer allows the development of connection objects of type Database, LDAP, or WCF Service. By default, there will always be an initial connection object called the MetastormDefault Connection, which connects to the MBPM Repository. This connection needs to be configured when the Designer is first used. Designer saves these settings for subsequent use. The steps below needs to be followed to configure the MetastormDefault Connection: MBPM Designer User's Guide 37 Chapter 10 Setting the Designer Options l Select the Default Connection option l On the Define Connection tab, select the provider: SQL or Oracle l Enter the name of the server l Enter authentication details l Enter the name of the MBPM Repository (for a default install, this will be Metastorm) l Click the Test Connection button If the connection is successful, you can explore the repository contents. l Scripting - provides the location for the assemblies. Note that you should only add folders that contain just the .NET assemblies that you would like to use. The assemblies copied into CustomLib folder should be compatible with the target platform (x86, x64, or CPU format). An assembly is a collection of functionality that is built, versioned, and deployed as a single implementation unit. Assemblies can be static or dynamic. Static assemblies can include .NET Framework types (interfaces and classes), as well as resources for the assembly (bitmaps, JPEG files, resource files, and so on). You can also use the .NET Framework to create dynamic assemblies, which are run directly from memory and are not saved to disk before execution. You can save dynamic assemblies to disk after they have executed. Note that 3rd party assemblies referenced by MBPM must be strongly named. For more information, please refer to the Microsoft documentation. Namespace is a logical naming scheme for types in which a simple type name is preceded with a dot-separated hierarchical name. For example, types MyOffice.FileAccess.Open and MyOffice.FileAccess.Edit might be logically expected to have functionality related to file access. A single assembly may contain many types whose hierarchical names have different namespace roots, and a logical namespace root may span multiple assemblies. Designer allows selecting the namespaces and thereby makes it easier to browse and reference types in their code. The selected namespaces will be included to all subsequently created Code Activities. The Intellisense tab allows you to choose whether you would like to display all the functions including the .NET framework functions or the functions of the Designer along with promoted functions. l l l l l Projects - provides you with an option to toggle the automatic saving of new items when saving a project. For more information on projects, see Creating a Project. Inventory - You can toggle the option to display items in the Inventory by a single click. For more information, see Inventory. Templates - set the locations for templates. For more information, see Templates. Logging - Errors, warnings, and information can be logged to a log file in your specified location. You can choose to display it in simple, verbose, or user text format. Backup - You can choose from None, Single, or Incremental. None: no backup of solution is created. Single: your existing saved solution is replaced with the latest solution.(default) 38 MBPM Designer User's Guide Chapter 10 Setting the Designer Options Incremental: a new backup of solution is made each time you save. l Display Quick Access Bar: Choose from list of commands from Available Commands list and move them to the Quick Access Bar. The items that you move to the Quick Access Bar will be displayed in the Show Quick Access Toolbar. The Reset docking layout button resets the Designer layout to the default settings. Task Pane: You can choose between Navigation Pane and Multiple Task Pane modes. Selecting Navigation Pane mode displays the Navigation pane. The Navigation Pane consists of Inventory, Properties, Toolbox, Repository, and Data Access navigation option buttons that are stacked to the left of the Designer window. Clicking on a button will launch the appropriate toolbar. You can control the number of buttons displayed either by clicking on the drop-down below the Data Access button or by re-sizing the Navigation Pane to display the desired buttons. In Multiple task pane modes, all the toolboxes can be toggled to be displayed or hidden by clicking in View tab and clicking the desired toolbox button. Also, the toolboxes can be moved around within the Designer. Docking and pinning of toolboxes is also possible. For more information, see Docking and Pinning Toolboxes. l MBPM Designer - displays the version of MBPM and is of use when contacting support. MBPM Designer User's Guide 39 40 MBPM Designer User's Guide Chapter 11 Designing a Project Chapter 11 Designing a Project When designing a project, the following should be considered: l What action initiates the project? l What tasks must be performed to complete the project? l In what order must these tasks be performed? l What individuals within the organization will be involved? l What roles will they be taking in the project? l What information needs to be gathered during the course of the project? l What information should be shared among participants? l What are the possible outcomes? l Does the project flow in a step-by-step manner from start to finish, or are there alternative paths that must be taken into consideration? That is, are actions taken sequentially or in parallel? l What elements of your design could be reused for other projects? l What happens when the project is run? Define the Initial Action When you define a new process, MBPM automatically creates a default project and attaches the process to it. Within the process, one or more initial user actions may be set to originate from the clapperboard as input into any stage. Each action must have a unique name and may be associated with a different form. Examples of such initial actions would be an incoming phone call or email message, a request for information or services, the beginning of multiple new projects and so on. Define and Prioritize Tasks The tasks required to complete the business process will be represented as stages and actions: l l A stage is where the folder is at in the process, that is, where it stops awaiting action. At these stages, the MBPM Process Engine or process users can act on the folders. Actions represent the tasks to be performed at various stages throughout the process. Actions may be: MBPM Designer User's Guide 41 Chapter 11 Designing a Project n n Complex – For example, they may require a process user to enter information on a form. Simple – For example, they may require approval before being passed on to the next stage of the process. Other actions may be performed by the system based on information pulled from the database or provided by a process user at an earlier point in the process. Identify Participants The participants in your project are identified by their roles within the project. Note: The system may also be a participant in the project, handling automated tasks. In this case, the system will be represented by a system stage rather than by a role assignment. Determine Necessary Information The type of task being performed determines the information needed and the routing of that information. The information you require will determine the forms you will need to create to accompany your project. Determine Possible Outcomes A project may have several possible outcomes that may affect the route a business process follows from start to finish. Identify Reusable Elements If you identify tasks that will be performed more than once within the process, consider creating a library. Libraries can be used to store common sub processes, forms, form segments, scripts, and roles. When an existing library is associated with a project its contents become available to that project. Maintain the Process The Find and Replace feature allows the process designer to locate (and update) all the places specific text is used in a process. By searching on caption names this feature can also be used to locate various process elements. 42 MBPM Designer User's Guide Chapter 12 Creating a Project Chapter 12 Creating a Project Creation of a project is automatic when you create a process. 1. To create a new project, select Application > New > Project. A new project is created in the Inventory. The project name is generated automatically, for example, Project1. 2. Right-click the project and click Open to set the project properties. 3. The Owner field is populated automatically with the login user name. 4. In the Description field, enter a brief description for the project. 5. In the Language pane, select the languages to be made available in the project and use the add button to add them to the right pane. 6. Click the MBPM button > Save. The solution is saved. Setting the Project Properties l l l Owner - the project creator or owner. This field is the same as the Owner field in the main pane. The name can be entered in either field. Company Name - an optional field to enter the name of the company, if required. Description - this field is the same as the Description field in the main pane. A brief project description can be entered in either field. Process Overview An MBPM process is a visual representation of a business process. A process is broken down into Stages and Actions. A stage is where a folder waits until an action is taken to leave the stage. A process contains the following elements: l A single start stage, from which new folders are created. l One or more stages where folders are held pending action. l One or more actions which are used to update a folder or move it to another stage. l Any number of Comments. Note: A process needs to have at least one archive stage. MBPM Designer User's Guide 43 Chapter 12 Creating a Project Elements of a Process 1. Start stage 2. Action 3. Stage 4. Process Lanes 5. Comment 6. Loopback action 7. Properties pane (showing properties for the currently selected item) 8. Individual properties of selected form or report control 9. Archive stage You can select the stages and actions from the process toolbox and add to the process to build the business process. You can use the properties pane to set process parameters at each stage and action. The Process Toolbox Stages, actions, comments and Sub-Processes are added to processes via the Process Toolbox. The Process Toolbox is a floating dialog box, which you may move or toggle on/off at your convenience. When a process or sub process is active, the Process toolbox is also displayed. To toggle the Toolbox on and off, select the View ribbon tab and click Toolbox. The process toolbox is displayed when you select a process. The process toolbox is divided into six sections: l Default - The Pointer button allows you to select a particular process stage or action. l Stages - The Stage buttons are used to add stages to the process. l Actions - The Action buttons are used to add actions to the process. l Miscellaneous - The Comments button is used to add a comments field to the process. l l Business Objects - A Business Object facilitates process designers to access and manipulate data in a business process. Roles - All of the default Designer roles and any new roles created in that project. Docking and Pinning Docking To dock a pane: 1. Click on the pane's title bar and drag the pane within the Designer. A set of docking icons are displayed. 2. Drag the pane on to one of the docking icon. A blue shaded area is displayed where the 44 MBPM Designer User's Guide Chapter 12 Creating a Project pane will be docked. 3. While holding the pane on the icon, release the mouse. The pane is docked. To undock a pane: 1. Click on the pane's title bar and drag the pane away from its docked position. The pane will now float. Pinning Once a pane is docked it can be set to show and hide by setting the auto-hide feature using the pinning buttons. Each pane has a pinning icon on the right side of its title bar . To auto-hide a pane, click on the pin button. The pane is tabbed to the nearest side and will now auto-hide. Hover the cursor over the tab to display the pane. To remove auto-hide, display the pane and click on the unpin button . Lanes A lane is a graphical representation of a role. It assists you to add roles to stages but not actions. Adding a Lane You can add a lane to a process by dragging a Role button from the toolbox and dropping it in the main pane of the process tab. Note: You can adjust the height of the lane and change the icon associated with a specific role. Lanes can be used in Basic or Enhanced process modeling mode. MBPM Designer User's Guide 45 Chapter 12 Creating a Project Editing Lane Properties Click on the Role icon in the Process to edit a lane's properties. Note: In the MBPM Designer, the process lanes have a StartBackground property that specifies the color gradient. This property enables color applied in a BPM Process model to be persisted when transformed into a ProVision model using the MBPM ProVision Connect tool. Moving Lanes You can shift a lane up or down by using drag-and-drop operation on a role icon in a process. Adding a Stage to a Lane When you add a stage to a lane, the role that it represents is automatically added to the To Do list. Moving a Stage from one lane to another When you move a stage from one lane to another, the role associated with the source lane is removed from the To Do list and the role associated with the destination lane is added. No other roles in the To Do list are affected. 46 MBPM Designer User's Guide Chapter 12 Creating a Project Deleting a Lane You can remove a lane that contains no stages from a process by selecting its button in the main pane and pressing the DELETE key. When you delete a lane, any of the lanes below it move up to fill up the space. Note: You cannot delete a lane if it contains any stages. Creating a Process Before starting to build your process, define the business process and identify the tasks and actions required to complete it. Whenever you create a new process, a default process is displayed in the main pane. This process will contain a Start stage (the Clapperboard) and a User stage connected by a User action. When you create a new process it will be assigned to the project that is currently open. If you do not have a project open, a default project will be created when you create the process. Create a Process To create a new process: 1. On the Home ribbon tab, Components group, click on the Process button. Alternatively, from Inventory, right-click on an object, click New > Process. The new process consists of a start stage and a user stage connected by a user action. 2. To display the process properties, click anywhere in the process, that is not occupied by a process element. In the Properties pane, edit the process properties as required. You can edit the process default name and caption. You can also change the default names for the start stage, first action and first stage. 3. Click the MBPM button > Save. Process Element Properties To specify the properties of a process, click anywhere in the process that is not occupied by a process element. The process name will appear in the Properties pane, together with a list of its properties. You can specify or alter any of the properties in the Properties pane. The following table lists all the processes and process elements and their properties. MBPM Designer User's Guide 47 Chapter 12 Creating a Project Archive stage Property Name Description Caption Choose a caption for this element. It is the caption which is visible at runtime. Name Specify a unique name to identify this element. This name is not visible at runtime. Position from top The position (in pixels) of this element, from the top edge of the process Position from left The position (in pixels) of this element, from the left hand side of the process design area. Associated icon Choose an icon to represent this item within Designer, if you do not want to use the default. When stage started Use this property to enter a visual script that is run when the stage is started Font color Choose a font color for this element. Background color Choose a background color for this element. Border color Choose a border (outline) color for this element. Forms Choose the order in which forms appear in the folder for this stage Notes Use this to enter any specific notes for anyone using this element within the Designer environment. Help URL A URL or expression which the help button will launch when clicked. Comment Property Name Description Comment Enter the text of your comment here Position from top The position (in pixels) of this element, 48 MBPM Designer User's Guide Chapter 12 Creating a Project Property Name Description from the top edge of the process Position from left The position (in pixels) of this element, from the left hand side of the process design area. Width Specify the width of the form, in pixels. Height Specify the height, in pixels, of this element. Font Choose a font color for this comment Font color Choose a font color for this element Background color Choose a background color for this element. Border color Choose a border (outline) color for this element. Alignment Choose an alignment style from the options displayed to position the text in the comment accordingly. Common stage Property Name Description Caption Choose a caption for this element. It is the caption which is visible at runtime. Name Specify a unique name to identify this element. This name is not visible at runtime. Associated icon Choose an icon to represent this item within Designer, if you do not want to use the default. Position from top The position (in pixels) of this element, from the top edge of the process Position from left The position (in pixels) of this element, from the left hand side of the process design area. Font color Choose a font color for this element. MBPM Designer User's Guide 49 Chapter 12 Creating a Project Property Name Description Background color Choose a background color for this element. Border color Choose a border (outline) color for this element. Applied to stages Stages to which this common stage applies When stage started Use this property to enter a visual script that is run when the stage is started When stage completed Use this property to enter a visual script that is run when the stage is completed Notes Use this to enter any specific notes for anyone using this element within the Designer environment. Conditional action Property Name Description Caption Choose a caption for this element. It is the caption which is visible at runtime. Name Specify a unique name to identify this element. This name is not visible at runtime. Associated icon Choose an icon to represent this item within Designer, if you do not want to use the default. Position from top The position (in pixels) of this element, from the top edge of the process Position from left The position (in pixels) of this element, from the left hand side of the process design area. Font color Choose a font color for this element. Priority The priority for this action (Actions always have a priority of 1 if they are the only action leaving a stage) Message Enter an alert message to be shown to the user. You can also use an expression to 50 MBPM Designer User's Guide Chapter 12 Creating a Project Property Name Description make the message more context sensitive. Only start action if Only start the conditional action if this formula returns a positive result. When action completed Use this property to enter a visual script that is run when the stage is completed Clone new folder Clone a new folder in this action, marking its parent folder as the original folder. The parent folder will remain; the cloned folder proceeds to the next stage. Notes Use this to enter any specific notes for anyone using this element within the Designer environment. Flag action Property Name Description Caption Choose a caption for this element. It is the caption which is visible at runtime. Name Specify a unique name to identify this element. This name is not visible at runtime. Associated icon Choose an icon to represent this item within Designer, if you do not want to use the default. Position from top The position (in pixels) of this element, from the top edge of the process Position from left The position (in pixels) of this element, from the left hand side of the process design area. Font color Choose a font color for this element. Message Enter an alert message to be shown to the user. You can also use an expression to make the message more context sensitive. Only start action if Only start the flag action if this formula returns a positive result. MBPM Designer User's Guide 51 Chapter 12 Creating a Project Property Name Description Clone new folder Clone a new folder in this action, marking its parent folder as the original folder. The parent folder will remain; the cloned folder proceeds to the next stage. When action completed Use this property to enter a visual script that is run when the stage is completed Priority The priority for this action (Actions always have a priority of 1 if they are the only action leaving a stage) Flag used to invoke this action Choose which flag should be used to cause this action to be initiated. Folder which must raise flag Specify the folder which must raise this flag Loopback options Choose what should happen to the to-do lists for the folder which is being looped back. Notes Use this to enter any specific notes for anyone using this element within the Designer environment. Group stage Property Name Description Caption Choose a caption for this element. It is the caption which is visible at runtime. Name Specify a unique name to identify this element. This name is not visible at runtime. Associated icon Choose an icon to represent this item within Designer, if you do not want to use the default. Position from top The position (in pixels) of this element, from the top edge of the process Position from left The position (in pixels) of this element, from the left hand side of the process design area. 52 MBPM Designer User's Guide Chapter 12 Creating a Project Property Name Description Font color Choose a font color for this element. Background color Choose a background color for this element. Border color Choose a border (outline) color for this element. Forms Choose the order in which forms appear in the folder for this stage To Do list Users who will see this stage on their ToDo list Watch list Choose the users who will see the folder on their watch list when it is at this stage When stage started Use this property to enter a visual script that is run when the stage is started When stage completed Use this property to enter a visual script that is run when the stage is completed Notes Use this to enter any specific notes for anyone using this element within the Designer environment. Help URL A URL or expression which the help button will launch when clicked. Linked process stage Property Name Description Caption Choose a caption for this element. It is the caption which is visible at runtime. Name Specify a unique name to identify this element. This name is not visible at runtime. Associated icon Choose an icon to represent this item within Designer, if you do not want to use the default. Position from top The position (in pixels) of this element, from the top edge of the process MBPM Designer User's Guide 53 Chapter 12 Creating a Project Property Name Description Position from left The position (in pixels) of this element, from the left hand side of the process design area. Font color Choose a font color for this element. Background color Choose a background color for this element. Border color Choose a border (outline) color for this element. Forms Choose the order in which forms appear in the folder for this stage Linked processes The processes associated with this stage When stage started Use this property to enter a visual script that is run when the stage is started When stage completed Use this property to enter a visual script that is run when the stage is completed To Do list Users who will see this stage on their To Do list Watch list Choose the users who will see the folder on their watch list when it is at this stage Notes Use this to enter any specific notes for anyone using this element within the Designer environment. Help URL A URL or expression which the help button will launch when clicked. Process Property Name Description Caption Choose a caption for this element. It is the caption which is visible at runtime. Name Specify a unique name to identify this element. This name is not visible at runtime. Subject Process description 54 MBPM Designer User's Guide Chapter 12 Creating a Project Property Name Description Prefix of folder name A prefix for folders generated by this process Limit access to Define which roles can access this process. Perform external events before local events Perform external events before local events Stages order The order of the stages in the process Length of numeric suffix Indicate how many digits should be used to form the folder's numeric ID. (This is the total number of digits which follows the 'prefix to folder name', defined above.) Notes Use this to enter any specific notes for anyone using this element within the Designer environment. Rendezvous action Property Name Description Caption Choose a caption for this element. It is the caption which is visible at runtime. Name Specify a unique name to identify this element. This name is not visible at runtime. Associated icon Choose an icon to represent this item within Designer, if you do not want to use the default. Position from top The position (in pixels) of this element, from the top edge of the process Position from left The position (in pixels) of this element, from the left hand side of the process design area. Font color Choose a font color for this element. Priority The priority for this action (Actions always have a priority of 1 if they are the only action leaving a stage) Linked processes Use this to choose which Sub-Processes MBPM Designer User's Guide 55 Chapter 12 Creating a Project Property Name Description must complete in order for the rendezvous action to release the folder to the next stage. Wait for all/any linked processes to complete Specify whether this rendezvous action should wait for any of the incoming linked processes to finish, or whether it must wait for all of them. Only start action if Only start this rendezvous action if this formula returns a positive result. When action completed Use this property to enter a visual script that is run when the stage is completed Message Enter an alert message to be shown to the user. You can also use an expression to make the message more context sensitive. Clone new folder Clone a new folder in this action, marking its parent folder as the original folder. The parent folder will remain; the cloned folder proceeds to the next stage. Notes Use this to enter any specific notes for anyone using this element within the Designer environment. Rules stage Property Name Description Caption Choose a caption for this element. It is the caption which is visible at runtime. Name Specify a unique name to identify this element. This name is not visible at runtime. Associated icon Choose an icon to represent this item within Designer, if you do not want to use the default. Position from top The position (in pixels) of this element, from the top edge of the process Position from left The position (in pixels) of this element, from the left hand side of the process 56 MBPM Designer User's Guide Chapter 12 Creating a Project Property Name Description design area. Font color Choose a font color for this element. Background color Choose a background color for this element. Border color Choose a border (outline) color for this element. Forms Choose the order in which forms appear in the folder for this stage Watch list Choose the users who will see the folder on their watch list when it is at this stage Rules Rules to run for this stage When stage started Use this property to enter a visual script that is run when the stage is started When stage completed Use this property to enter a visual script that is run when the stage is completed Notes Use this to enter any specific notes for anyone using this element within the Designer environment. Help URL A URL or expression which the help button will launch when clicked. Start stage Property Name Description Name Specify a unique name to identify this element. This name is not visible at runtime. Associated icon Choose an icon to represent this item within Designer, if you do not want to use the default. Position from top The position (in pixels) of this element, from the top edge of the process Position from left The position (in pixels) of this element, from the left hand side of the process design area. MBPM Designer User's Guide 57 Chapter 12 Creating a Project Property Name Description Font color Choose a font color for this element. Background color Choose a background color for this element. Border color Choose a border (outline) color for this element. Notes Use this to enter any specific notes for anyone using this element within the Designer environment. Sub-Process Property Name Description Caption Choose a caption for this element. It is the caption which is visible at runtime. Name Specify a unique name to identify this element. This name is not visible at runtime. Stages order The order of the stages in the process Notes Use this to enter any specific notes for anyone using this element within the Designer environment. Sub-Process stage Property Name Description Caption Choose a caption for this element. It is the caption which is visible at runtime. Name Specify a unique name to identify this element. This name is not visible at runtime. Position from top The position (in pixels) of this element, from the top edge of the process Position from left The position (in pixels) of this element, from the left hand side of the process design area. Font color Choose a font color for this element. 58 MBPM Designer User's Guide Chapter 12 Creating a Project Property Name Description Background color Choose a background color for this element. Border color Choose a border (outline) color for this element. Associated icon Choose an icon to represent this item within Designer Sub-Process Sub-Process for this Sub-Process stage Forms Choose the order in which forms appear in the folder for this stage When stage completed Use this property to enter a visual script that is run when the stage is completed Notes Use this to enter any specific notes for anyone using this element within the Designer environment. Help URL A URL or expression which the help button will launch when clicked. System stage Property Name Description Caption Choose a caption for this element. It is the caption which is visible at runtime. Name Specify a unique name to identify this element. This name is not visible at runtime. Associated icon Choose an icon to represent this item within Designer, if you do not want to use the default. Position from top The position (in pixels) of this element, from the top edge of the process Position from left The position (in pixels) of this element, from the left hand side of the process design area. Font color Choose a font color for this element. Background color Choose a background color for this MBPM Designer User's Guide 59 Chapter 12 Creating a Project Property Name Description element. Border color Choose a border (outline) color for this element. Forms Choose the order in which forms appear in the folder for this stage Watch list Choose the users who will see the folder on their watch list when it is at this stage When stage started Use this property to enter a visual script that is run when the stage is started When stage completed Use this property to enter a visual script that is run when the stage is completed Auto-forward folders to Pick a stage to which you want folders reaching this stage to be forwarded to automatically. Notes Use this to enter any specific notes for anyone using this element within the Designer environment. Help URL A URL or expression which the help button will launch when clicked. Timed action Property Name Description Caption Choose a caption for this element. It is the caption which is visible at runtime. Name Specify a unique name to identify this element. This name is not visible at runtime. Associated icon Choose an icon to represent this item within Designer, if you do not want to use the default. Position from top The position (in pixels) of this element, from the top edge of the process Position from left The position (in pixels) of this element, from the left hand side of the process 60 MBPM Designer User's Guide Chapter 12 Creating a Project Property Name Description design area. Font color Choose a font color for this element. Timed event A variable or formula before or after which to start this action. Message Enter an alert message to be shown to the user. You can also use an expression to make the message more context sensitive. Clone new folder Clone a new folder in this action, marking its parent folder as the original folder. The parent folder will remain; the cloned folder proceeds to the next stage. Only start action if Only start the timed action if this formula returns a positive result. When action completed Use this property to enter a visual script that is run when the stage is completed Start this action When to start the action Duration Choose the length of time that this timed action should wait, before the folder proceeds to the next stage. Before / After Choose whether to Start this action before or after specified interval Priority The priority for this action (Actions always have a priority of 1 if they are the only action leaving a stage) Loopback options Choose what should happen to the to-do lists for the folder which is being looped back. Notes Use this to enter any specific notes for anyone using this element within the Designer environment. User action Property Name Description Caption Choose a caption for this element. It is the MBPM Designer User's Guide 61 Chapter 12 Creating a Project Property Name Description caption which is visible at runtime. Name Specify a unique name to identify this element. This name is not visible at runtime. Description Enter a description for this action. This appears as the description at the start of the process. Associated icon Choose an icon to represent this item within Designer, if you do not want to use the default. Position from top The position (in pixels) of this element, from the top edge of the process Position from left The position (in pixels) of this element, from the left hand side of the process design area. Font color Choose a font color for this element. Form Choose a form to associate with this action. When the user reaches this action, the form you choose here is the one that will be shown. Form field Property behavior for this form Clone new folder Clone a new folder in this action, marking its parent folder as the original folder. The parent folder will remain; the cloned folder proceeds to the next stage. When action started Use this property to enter a visual script that is run when the stage is started When action completed Use this property to enter a visual script that is run when the stage is completed Chained action Indicate whether or not you want to run a chained action from this user action. Chained action name If you've chosen to run a chained action, use this property to specify the required action. You may use an expression to dynamically choose the appropriate action. 62 MBPM Designer User's Guide Chapter 12 Creating a Project Property Name Description Message Enter an alert message to be shown to the user. You can also use an expression to make the message more context sensitive. Confirm action Choose whether the user needs to confirm this action. (Only available if no form is associated to the action.) Priority The priority for this action (Actions always have a priority of 1 if they are the only action leaving a stage) Re-open folder Return the user to this folder when the action is submitted Available to roles Specify which roles are allowed to perform this action Only show Action if When a Form is evaluated at runtime for a stage, if the user has the role and the condition evaluates to true, the Action is displayed. Otherwise, the Action is not displayed. The default value is blank, which is interpreted as "true" for the condition. Loopback options Choose what should happen to the to-do lists for the folder which is being looped back. Notes Use this to enter any specific notes for anyone using this element within the Designer environment. Help URL A URL or expression which the help button will launch when clicked. User stage Property Name Description Caption Choose a caption for this element. It is the caption which is visible at runtime. Name Specify a unique name to identify this element. This name is not visible at runtime. MBPM Designer User's Guide 63 Chapter 12 Creating a Project Property Name Description Associated icon Choose an icon to represent this item within Designer, if you do not want to use the default. Position from top The position (in pixels) of this element, from the top edge of the process Position from left The position (in pixels) of this element, from the left hand side of the process design area. Font color Choose a font color for this element. Background color Choose a background color for this element. Border color Choose a border (outline) color for this element. To Do list Users who will see the folder on their to-do list when it is at this stage Watch list Choose the users who will see the folder on their watch list when it is at this stage When stage started Use this property to enter a visual script that is run when the stage is started When stage completed Use this property to enter a visual script that is run when the stage is completed Forms Choose the order in which forms appear in the folder for this stage Notes Use this to enter any specific notes for anyone using this element within the Designer environment. Help URL A URL or expression which the help button will launch when clicked. 64 MBPM Designer User's Guide Chapter 13 Introduction to Sub-Processes Chapter 13 Introduction to Sub-Processes Sub-Processes allow the process to be broken down into portions that can be re-used in any process in the project. They can be used for portions of processes that are repeated. This saves the process designer from creating the portion more than once. They may also be used to break down a large process into several smaller processes. In earlier versions of MBPM, Sub-Processes were called map segments. Sub-Processes are designed in much the same way as processes except that the first action within a Sub-Process has no properties and is not removable. When a folder arrives at a Sub-Process stage, it drops into the Sub-Process. It progresses through the stages of the Sub-Process until it arrives at an archive stage. This is a virtual archive stage. It indicates that the folder should leave the Sub-Process stage (on the “top level” process) by one of the rendezvous actions leaving that stage. When folder comes to the end of the Sub-Process, it rejoins the main process. 1. The same folder flows through main process and Sub-Process. 2. Main process waits at Sub-Process stage until the Sub-Process is completed. 3. Sub-Processes must have same exit and re-entry point on the main process. 4. Sub-Processes can be nested within other Sub-Processes. 5. A Sub-Process has its own Business Object to hold local variables and their values. MBPM Designer User's Guide 65 Chapter 13 Introduction to Sub-Processes Sub-Process Rules l Any action can lead into a Sub-Process stage. l Only Rendezvous actions may lead out of a Sub-Process stage. Sub-Process Properties l Sub-Processes can have multiple end points, but only one starting point. l Sub-Processes can be nested, that is, they may contain other Sub-processes. Creating Sub-Processes To create a new Sub-Process, on the Home ribbon tab Components group, click SubProcess. The Designer creates a default Sub-Process in the main pane. The new Sub-Process consists of a start stage and a user stage connected by a user action. In the Properties pane, edit the Sub-Process properties as required. Note: Sub-Processes are added by dragging and dropping on to a parent process. Adding a Sub-Process to a Process The following steps describe how to add a Sub-Process to a main process, or another SubProcess: 1. Create the Sub-Process. A new Sub-Process section is added to the Process toolbox and the newly created SubProcess is displayed in it. 2. In the main process, drag and drop the Sub-Process from the Sub-Processes pane. Note: You can only draw a Rendezvous action from a Sub-Process stage. Using Sub-Processes The same Sub-Process can be reused several times in the same process and can also be used in other processes in the same project. 66 MBPM Designer User's Guide Chapter 13 Introduction to Sub-Processes If the Sub-Process is added to a library it can also be used within other projects in the solution. Nested Sub-Processes Sub-Processes can be nested. For example, to nest two Sub-Processes to a top process: 1. Create the Sub-Processes. 2. In the top process attach the first Sub-Process. 3. In the first Sub-Process, attach the second Sub-Process. MBPM Designer User's Guide 67 68 MBPM Designer User's Guide Chapter 14 Introduction to Linked Processes Chapter 14 Introduction to Linked Processes Linked Process stages are used to display a number of linked processes, each of which will create a “child folder” that can be processed simultaneously or in parallel to the main process. Linked processes should only be used when there is a requirement for the parent folder to wait until the child folders have finished processing before the parent folder continues on through its process. If this requirement does not exist, the project should raise a flag to start a new folder in another process. Linked Process stages may also be used in conjunction with rendezvous actions to place the parent process “on hold” status until one or more linked processes are completed. Each time a folder arrives at a Linked Process stage, a child folder is initiated in each Linked Process. Because of this inherent functionality, loop-back actions may not be desirable for linked process stages. Each time a loop-back action is triggered a new set of child folders will be created. MBPM Designer User's Guide 69 Chapter 14 Introduction to Linked Processes In the above example, Process 2 and Process 3 are run in parallel with Process 1. Linking Processes 1. You can only link a parent process to other processes within the same project. 2. Create the parent process. 3. Use the New Process function to create the process to which you want to link the parent. 4. In the parent process, add a Linked stage. 5. Select the linked stage, in the properties pane, click on the Linked processes drop-down. The Linked stage properties contain a list of all processes. The system updates this list as new processes are created within the project. 6. Select the linked processes you wish to display at this point from the list displayed. You may check all the linked processes that apply. If you have not yet created the desired linked processes, you may return to this list after the processes have been created and select them at that time. 7. Click OK. The selected processes are now linked. 70 MBPM Designer User's Guide Chapter 14 Introduction to Linked Processes Note: When a child process is linked, a flag is raised. Note that the flag added to linked processes should not be deleted. Nested Linked Processes Linked processes can be nested. To nest linked processes to a top process: 1. Create the linked processes. 2. In the top process attach the first linked process. 3. In the first linked process, attach the second linked process. MBPM Designer User's Guide 71 72 MBPM Designer User's Guide Chapter 15 Working with Processes Chapter 15 Working with Processes Adding Stages to a Process To add a stage to the process: 1. From the Toolbox, drag and drop the required type of Stage. 2. Click on the process where you wish to place the stage. 3. In the properties pane, edit the stage properties as required. The Designer will allocate a default name (for example GroupStage1). You can move stages around the main pane of the Designer by selecting them and dragging them to the desired location. Any action lines attached to the stage will be automatically adjusted as you move the stage. Defining the Process Stage Order The Stages Order property enables you to establish the stage priority for each stage on the process. The stages pass their priority to the actions originating from them. If the common stage is higher on the Stages Order list, the conditional actions from the common stage will be assessed before the conditional actions on the other stage. The default order of the stages on the Stages Order tab is defined by the order in which the stages are originally added to the process. Set the Stage Order To set the Stage Order for stages on your process: 1. In the Process Properties pane, click in the Stages field to display the popup menu showing the current order sequence. 2. Select a stage from the list, and use the up and down arrow buttons to move the stage in the order sequence. 3. Click outside the list menu to save the changes. Adding Actions to a Process Actions can run directly between stages or loopback to the same stage. MBPM Designer User's Guide 73 Chapter 15 Working with Processes Add a Direct Action To add an action to a process: 1. In the Toolbox pane, Actions section, click on the required action type. 2. Click on the stage that represents the source of the action. 3. Drag the action from the source stage to the destination stage of the action. A line is displayed from the source stage to the destination stage. MBPM Designer automatically assigns a default name (for example UserAction1). 4. Edit the action properties. 5. To move actions, select the action and drag it to a new location. Add a Loopback Action You can draw any type of action other than a Rendezvous action so that the source and destination stages are the same. Such an action is called a loopback action. To add a loopback action: 1. In the Toolbox pane Actions section, click on the required action type. 2. Click on the stage that is to be the source and destination of the action and release the mouse button (do not drag). An action line is drawn that loops back to the same stage. You may need to drag the loopback action out from the stage to view it clearly. Changing the Action Style To change the type of action line style: 1. Select the Design tab and then click Line Styles. 2. Select a line style from the drop-down gallery. The selected style is applied to the action. Icons and Event Handlers Icons To hide the icons associated with process elements, select the Design tab and then click Icons. The icons for stages and actions are not displayed for the processes. Click Icons again to display them. Event Handler To hide the event handler icons associated with process elements, select the Design tab and then click Event Handlers. 74 MBPM Designer User's Guide Chapter 15 Working with Processes The event handler icons for stages and actions are not displayed for the processes. Click on Event Handlers button again to display them. Adding Comments to a Process A Comment allows you to annotate your process with descriptive notes about the stages and actions it contains. This makes the logic in your process easier for others to understand. You can place any number of comments directly on the process to provide extra information for yourself and other designers. Comment Action Rules You cannot draw actions to or from a comment. Add a Comment To add a comment to a process: 1. In the Toolbox pane, Miscellaneous section, click on Comment. 2. Click on the process where the comment is to be placed. A comment box is placed on the process. 3. Click inside the comments box and type the comment. You can also type the comment in the Properties > Comments Text field. Tip: To enter new line in a Comment field, press CTRL+Enter. 3. To move the Comments box, drag it to a new location. 4. To resize the Comments box, drag the handles. 5. You can enter a name for the comments in the Properties editor. Change the Comment Shape and Content Style You can change the shape of the comment box and the style of the contents. To change comment shape: 1. Select the Comment. 2. Select the Processes tab and then click on Shape Styles. 3. Select a shape style from the drop-down gallery. Change Style of Comment Contents In the process, select the Comment, the comment properties are displayed. To specify the font in which the comments are to be displayed, in the Properties editor scroll through the available drop-down, or click on the Fonts button. (Designer displays the standard Font dialog box and you can select the font, text color and size you require.) MBPM Designer User's Guide 75 Chapter 15 Working with Processes Selecting Process Elements To o move a process element or to display the corresponding Properties editor, you must select it. To select a process element, click the Pointer button and then click the process element. Click anywhere on the element and drag it to its new position. To select multiple process elements, perform one of these actions: l l l l Place your cursor over a point on the process, click and hold the left mouse button and, drag your cursor to encompass all of the desired process elements. Designer will display a dashed line indicating the outer edges of your selection. All items within the dashed line will be selected when you release the mouse button. From the Process toolbox, choose the Pointer button, and click on a process element. Then, holding either the Shift or the Ctrl keys, select any additional elements desired. Press Ctrl + A. MBPM Designer selects all elements currently on the process. If you have selected multiple process elements, the handles surrounding each selected element will be grayed out. You may move the elements as a group to another position on the process. You may also cut, copy or delete them as a group. Copying Process Elements You can copy process elements. To copy process elements: 1. Select one or more process elements using the [Ctrl] or [Shift] keys. 2. Perform one of these actions: n Select the Home ribbon tab, in the Clipboard group click Copy. n Right-click and select Copy. 3. To paste the process element, select the process that you want to paste the clipboard contents. (It is not necessary to select the process if you want to paste into the same process.) n Select the Home ribbon tab, in the Clipboard group click Paste. n Right-click and select Paste. You may need to drag the pasted content to ensure that it does not overlap existing process elements. If pasted elements have the same name as existing elements, they will be renamed by adding a digit to the end of the name to avoid confusion. For example, if you copy a stage called Approval and paste it into the same process, the pasted stage will be renamed Approval1. If you copy an action and paste it into the same process, the pasted action will have the same source and destination stages as the copied action. If you paste a copied action 76 MBPM Designer User's Guide Chapter 15 Working with Processes into a different process, it will be pasted into the process without any source or destination stage. Deleting Process Elements You can remove process elements from a process using either of the following methods: l Select the element and press the DELETE key on your keyboard. l Right-click on the element and select Delete from the shortcut menu. l Select the element, and in the Home ribbon tab Clipboard group, click Cut. When a stage is deleted the associated actions remain. Process elements that are Cut are saved in the clipboard, and may be pasted back onto the same or another process in the project. Process elements that are deleted using the Delete function are not stored. However, you may use the Undo option in the Quick Access toolbar to restore deleted items immediately. Changing Fonts and Colors of Process Elements You can change the font and color of process elements using the Design tab of the ribbon menu. To change font or color: 1. Open the process. 2. Select the appropriate process element. 3. To change the font, in the Design tab of ribbon change the font color, font name, and font size. 4. To change the color, in the Design tab of ribbon change the background color and border color. You can also use the Designer Options to set the default background and border color. MBPM Designer User's Guide 77 78 MBPM Designer User's Guide Chapter 16 Stage Types Chapter 16 Stage Types A stage is where the folder is at in the process, that is, where it stops awaiting action. Stages may require human intervention or they may be progressed automatically, either by querying existing data in the folder or by adding more data to the folder. When a folder arrives at a particular stage, it is made available to selected business users through the client interface for examination or action. There are nine types of stages: Stage Type Icon Description Clapperboard The Clapperboard represents the starting point of a process. When you create a process the Designer inserts a Clapperboard by default, with a single User action leading to a single User stage. User Where action is required by a single specified user. Group Where action is required by one (non-specific) member of a group. Sub-Process Allows you to reuse common portions of a process. When a folder reaches a sub process stage, it enters the specified sub process. When it comes to the end of the Sub-Process, it rejoins the main process. MBPM Designer User's Guide 79 Chapter 16 Stage Types Stage Type Icon Description There is no generic stage for Sub-Process in the toolbox. You need to create a Sub-Process from the Components group. Linked Process Interrelated processes may need to complete in parallel. A Linked process stage is used to achieve this by linking additional processes to the main process. A Linked process stage can be triggered to continue when one or all of its linked processes have finished. Rule A rule can be invoked from a Business Rules Engine. System Where system/automation action is required (that is no user intervention is required). Common Actions from a common stage can be applied to multiple stages, eliminating the need for duplicate actions around several different stages. Archive When a folder reaches an archive stage the process is completed and the folder is no longer active and cannot be viewed by the client. The information remains in the database and can be reported on using the reporting tools. 80 MBPM Designer User's Guide Chapter 16 Stage Types Clapperboard (Start Stage) The Clapperboard represents the starting point of a process. When you create a process the Designer inserts a Clapperboard by default, with a single User action leading to a single User stage. You cannot remove the Clapperboard from a business process, and you cannot add another. The user action that initiates from the start stage is called the initiating action. Clapperboard Rules The following restrictions apply to the Clapperboard stage. l l l You can move the Clapperboard within the process, but you cannot remove it from the process. You cannot draw conditional, timed, or rendezvous actions coming from the Clapperboard. You cannot draw any type of action going into the Clapperboard. User Stage A User stage represents a point in a process at which a particular business user is expected to take some action. When a folder reaches a User stage it is placed in a specific business user’s To Do list in the client interface. User Stage-Action Rules l You can draw any type of action going into a User stage. l You can draw any type of action except a Rendezvous action coming from a User stage. Group Stage A Group stage represents a point in a process at which any process user associated with a particular role can take action. When a folder reaches a Group stage it is placed on the To Do list of every business user associated with a specific role. Group Stage Action Rules l You can draw any type of action going into a Group stage. l You can draw any type of action except a Rendezvous action coming from a Group stage. Sub-Process Stage Sub-Process stages replace what were referred to in a previous release of Designer as 'map segment' stages. MBPM Designer User's Guide 81 Chapter 16 Stage Types Note: You have to create a Sub-Process stage from the Components tab before it appears in the toolbox as there is no longer a generic Sub-Process stage. Sub-Process stages allow the main process to be broken down into reusable portions that can be used in any process. They can be used for portions of processes that are repeated. This saves the process designer from creating the same portion more than once. The effect of a folder reaching a Sub-Process stage is that the folder then passes through the stages and actions defined in the Sub-Process before returning to the Sub-Process stage and continuing through the main process. Sub Process Stage Action Rules l You can draw any type of action going into a Sub-Process stage. l You can only draw a Rendezvous action coming from a Sub-Process stage. Linked Process Stage Linked process stages replace what were referred to in a previous release of Designer as Sub Procedure stages. A Linked Process stage allows you connect one or more processes that can be performed in parallel with the main process. A Linked Process stage has the following characteristics: l l l A Linked Process stage can call multiple processes, each of which is processed in parallel. When a folder reaches a Linked Process stage the Engine creates a child folder for each Linked Process named by the linked stage, and it is this child folder that is used within each of the Linked Processes. The original folder is unchanged. Linked process stages can be queued to resume when one or all of its linked processes have finished. Linked Stage Action Rules l You can draw any type of action going into or coming from a Linked Process stage. Rule Stage A Rule stage allows you to execute a rule in a Business Rules Engine as part of your process. The advantage of executing a rule from the Rules property is that the rule is executed after the form is submitted, rather than as part of Submit processing, so that control is returned to the client sooner. Rule stage Action Rules l You can draw any type of action going into a Rule stage. l You can draw any type of action except a Rendezvous action coming from a Rule stage. 82 MBPM Designer User's Guide Chapter 16 Stage Types System Stage A System stage represents a point in a process at which the Engine is expected to take some action, without the involvement of any business user. When a folder reaches a System stage it is handled automatically by the Engine. The folder will not appear on any business user’s To Do list. System Stage Action Rules l l You can draw any type of action going into a System stage. You can draw any type of action except a Rendezvous action coming from a System stage. Common Stage Common stages are used in cases where the same sequence of steps occurs at several points in the business process. To create a Common stage: 1. Create a Common stage where you have set of actions that should be performed. 2. Link Common stage to the stages from where it needs to be invoked through Properties task pane. Common Stage Action Rules l l You can draw a loop back action from a Common stage to itself. However, you cannot draw any type of action going into a Common stage. You can draw any type of action except a Rendezvous action coming from a Common stage. Archive Stage An Archive stage represents a logical end point for a business process. A process may include several Archive stages, since a process can have several different outcomes. For example, a travel request has been accepted and a flight has been booked, or the travel request has been rejected. When a folder reaches an Archive stage it is no longer visible in the client interface, although it can still be examined using MBPM Administrative Tools. Archive Stage Action Rules l You can draw any type of action going into an Archive stage. l You cannot draw any type of action coming from an Archive stage. Deleting a Stage To delete a stage from a process, either: MBPM Designer User's Guide 83 Chapter 16 Stage Types l Right-click on the stage and select Delete from the context sensitive menu. l Select the stage and press the DELETE key. The stage is deleted from the process. Any associated actions will remain in place and must be deleted separately. 84 MBPM Designer User's Guide Chapter 17 Action Types Chapter 17 Action Types An action is where a folder is progressed either by human intervention or automatically. MBPM defines the step or activity necessary to modify data and/or move a folder from one stage to the next as an action. Examples of actions may include activities such as: l Filling out a form. l Logging a telephone call. l Reviewing an attached file. l Approving or denying a request. Examples of actions that do not require human intervention: l Determining the routing for a folder based on information available in a folder or in a database. l Raising or responding to an event. l Moving a folder after a timed event. l Starting an external application. You can set properties in the MBPM Designer to accommodate a wide variety of possible business activities. There are five types of actions: Action Type Icon Description User Actions performed by the user, for example the entry of data. Timed Actions triggered after a set time period before or after a specific event. Conditional Actions executed when their Only start action if property is met. Rendezvous This action can be linked from a Linked Process stage. Once one or more MBPM Designer User's Guide 85 Chapter 17 Action Types Action Type Icon Description processes have been completed, any folder waiting at the Linked Process stage can be moved on using the Rendezvous action. Flag Within a MBPM process, Flag actions are used to send messages between processes and/or external applications. A process may contain several processes allowing actions in one folder's life cycle to influence the actions performed upon another folder. Flag actions trigger messages which indicate that event has occurred and to pass data between processes. Keep in mind the following when working with actions: l l l The first action that is executed in a process is called a creation action. It can be changed to a flag action but cannot be changed to a conditional, timed or rendezvous action. Creating a process where the creation action is chained to an action that uses the To Do List role is not supported. An error is displayed when you attempt to invoke a folder of this process. An action created within a process in the Designer may be in a connected or unconnected state (i.e. to a stage). In order to differentiate between a connected and unconnected action, unconnected actions are represented using dashed lines. Loopback Actions A loopback action is one that begins and ends at the same stage. It updates a folder but does not move it on to a different stage. User Action A User action is invoked by a user, possibly requiring the user to enter data via a form. 86 MBPM Designer User's Guide Chapter 17 Action Types User Action Rules The following rules apply to user actions: l You can draw User actions from any stage except an Archive. l You can draw User actions to any stage except a Common stage. l User actions can be loopback actions. l You can draw any number of User actions from the Clapperboard. l l If you draw more than one User action from a stage, they will be shown in the client folder in the order of the set in the priority property. User actions are the only actions that can display a form to a process user. Timed Action A Timed action is initiated at a specified interval after a specific event in the life of a folder. Timed Action Rules The following rules apply to timed actions: l You can draw Timed actions from any stage except Archive stages or the Clapperboard. l You can draw Timed actions to any stage except a Common stage. l Timed actions can be loopback actions. Note: To make a loopback timed action run more than once, follow one of the following options: l l Use the ProcessContext.WhenFolderLastUpdated variable in the Timed Event property of the loopback timed action. Use a DateTime variable as the Timed Event where the time value is later than ProcessContext.WhenFolderLastUpdated. Note: Loopback timed actions will only run once if the above condition is not met. Conditional Action A Conditional action is initiated automatically if a specified logical condition is evaluated by the Engine to be true. The condition is evaluated when a folder arrives at a stage, and is reevaluated each time a loopback action is processed for the stage. Conditional Action Rules The following rules apply to conditional actions: l You can draw Conditional actions from any stage except Archive stages. l Conditional actions can be loopback actions. l You cannot draw Conditional actions from the Clapperboard. l If you draw more than one Conditional action from a stage, they will be evaluated in the order of priority set by the Priority property. MBPM Designer User's Guide 87 Chapter 17 Action Types Rendezvous Action A Rendezvous action can be invoked when a folder in a process of a Linked Process stage ends. You can set a Rendezvous action to trigger when one or all processes reach completion. Rendezvous Action Rules The following rules apply to rendezvous actions: l You can draw Rendezvous actions only from a Linked or Sub-Process stage. l You can draw Rendezvous actions to any stage except a Common stage. l If you draw more than one Rendezvous action from a stage, they will be evaluated in the order of the priority set by the property. Flag Action A flag action is invoked when the Engine is informed that a specified event has occurred. This may be the result of: l Action taken in the same process. l Action taken in a different process. Flag Action Rules The following rules apply to flag actions: l You can draw flag actions from any stage except an Archive stage. l You can draw flag actions to any stage except a Common stage. l Flag actions can be loopback actions. l You can draw multiple flag actions from the Clapperboard. Loopback Action You can draw an action where the source and destination stages are the same. Such an action is called a loopback action. The action type can be any action except a Rendezvous action. A loopback action is any action that updates a folder, but does not move it on to a different stage. By default, when a loopback action is taken on a folder, MBPM does not regenerate the list of users who have the folder on their To Do or Watch lists. It simply updates the details for this folder in each list. Using the properties on the Roles tab for a loopback action, you can modify this functionality so that the To Do and Watch lists are regenerated. Add a Loopback Action To add a loopback action: 1. In the Toolbox pane Actions section, click on the required action type (excluding Rendezvous actions). 88 MBPM Designer User's Guide Chapter 17 Action Types 2. Click on the stage that is to be the source and destination of the action and release the mouse button (do not drag). An action line is drawn that loops back to the same stage. You may need to drag the loopback action out from the stage to view it clearly. MBPM Designer User's Guide 89 90 MBPM Designer User's Guide Chapter 18 Introduction to Folders Chapter 18 Introduction to Folders A folder is set of data that progress through the process. Each time a business process is initiated, the system creates a folder containing one or more forms. When an end-user opens the folder, these forms are displayed on separate tabs. At the bottom of the window, action buttons are displayed. Users can add or edit the information on the folder forms by clicking on actions. A folder can also contain documents. These documents are attached to the folder using a clip. The MBPM developer designs the process that the folder follows by specifying the stages and actions on a process and designing the forms that are linked to the actions. Another important part of the folder concept is that there is only ever one copy of a folder passing through the process at any one time. This means there is no duplication and everyone involved in the process is working from the same source of information. During the lifetime of a folder, the forms contained within it can change as the requirements of the workflow dictate. Controls on a form can be set to be hidden, read-only, required, or optional, and these attributes can be set differently at each stage. Folder ID As a folder is created, it is automatically assigned a unique identifier – this is called the folder ID. This unique identifier negates the need for designers to build such identifiers into their projects. The folder ID is stored in the database. MBPM developers can use the folder ID to query the MBPM database tables. Folder Name As a folder is created, it is automatically assigned a folder name. This name is comprised of a textual prefix concatenated with a numerical suffix. You can specify what the textual prefix should be and how long (number of digits) the numerical suffix should be. The folder name is displayed on the MBPM desktop interface. It acts as a descriptive tracking number for the folder. Cloning Folders The Clone new folder property copies the folder from the stage the action is coming from to the stage the action is going to. The original folder is left behind. This property is not available for the first action. MBPM Designer User's Guide 91 Chapter 18 Introduction to Folders All actions, except the first action, have the Clone new folder property. When this property is set, a copy of the folder is created when the action is taken. This copy will include all of the folder’s data but will have a different Folder Name and Folder ID. If the action advances the folder from one stage to another, only the cloned copy of the folder will advance. Note: When you select the Clone new folder property for a system action leading to a user stage, the To Do list property of user stage should be set to Everybody role instead of the default Originator role. This is because with the default Originator role, the cloned folder's originator becomes a system action and therefore the folder will not be visible to any user in the To Do list of MBPM Web Client. 92 MBPM Designer User's Guide Chapter 19 Introduction to Libraries Chapter 19 Introduction to Libraries A library is published to the MBPM repository database in the same way as a project. A library can be used to store parts that will be of use in more than one project. When a library is associated with a project its contents become available to that project. Libraries have a number of advantages: l l l l New projects may be created more quickly – existing libraries may be associated with new projects Maintenance of projects is simpler – if a form that is used in several projects needs to be updated, it need only be updated in the library. Once a project is redeployed with the latest version of the library, the updated form becomes available to users of that project. Increased accuracy – by maintaining one copy of a commonly used part, the likelihood of introducing an error is minimized. More than one process designer can build projects simultaneously – each process designer works on a library. These libraries are then brought together in one project file. One or more libraries can be attached to any project file. Once a library is attached to a project, all of the elements in that library are available to the project. If a library is updated, the process designer will be warned the next time when they open the project. You can store the following components in a library: l Business Objects l Client Scripts l Connections l Custom Lists l Flags l Form Segments l Forms l Roles l Server Scripts l Sub-Processes l Visual Scripts MBPM Designer User's Guide 93 Chapter 19 Introduction to Libraries Creating a Library To create a new library, on the Home ribbon tab, Components group, click on the Library button. A new empty library is added to the Inventory. The empty library will consist of the following: l Connections l Roles Adding Items to Library To add an item to a library: 1. In the Inventory tab, select the Library. 2. Right-click on Library, click New, and create the new item from the list. Any item in the list except for Project and Library can be added to the current library. In the Inventory, the new item is added to the library. Associating Library with a Process To associate a library with a process: 1. Deploy the Library. 2. Click the Repository tab in the Navigation pane, right-click on MBPM Deployment Service and click Refresh. 3. The deployed library with version numbers (for example, v1, v2, v3, etc) is displayed. You can right-click on a version and choose from the following: l Add this library to current project See step 5 for details. l Retrieve Click on this menu item to save your library to a location on your computer. l Add to local storage This will add the chosen version to the user's Offline Library Storage. You can choose this option if you need the library to be locally available without connecting to MBPM Service (that is, work offline.) 4. In the Inventory tab, click on the Project to which you would like add the library. 5. In the Repository tab, right-click on the chosen version of the library and click Add this library to current project. The chosen version of the library is attached to the solution. 94 MBPM Designer User's Guide Chapter 19 Introduction to Libraries Associating Library with a Process of another Solution After a library is created and if you would like to add it to a project in another solution: 1. Open the solution to which you would like to reference a library that is already available. 2. In the Inventory tab, click on the Project to which you would like to reference the library. 3. In the Repository tab, right-click on the chosen version of the library and click Add this library to current project. 4. Go back to the Inventory tab. A new item called Referenced Libraries is displayed. The version that you have chosen in earlier step is added to it. If a newer version of the library is available, an exclamation icon and a tool tip is displayed with the library name icon suggesting that you can right-click and choose Update to get the latest version of the library. You will be prompted that the newer version will replace the existing version. Click Yes to get the latest version. MBPM Designer User's Guide 95 96 MBPM Designer User's Guide Chapter 20 Designing a Form Chapter 20 Designing a Form Guidelines When designing a form in MBPM: l l l l l l Avoid large forms with a lot of controls as they may be difficult to use, slow to publish and slow to display. If necessary, you can divide form controls across a number of forms linked together by chained actions (effectively, a multi-page form). If the same controls are required on many forms, group such controls together in a form segment that can then be included in any forms that need to display that information. Before building the form, create a worksheet summarizing the information the form is to collect and display. Paper forms are not always good models for the design of electronic forms. In MBPM, you can set field visibility on forms and you can display multiple forms on different tabs at stages in the process. This provides greater flexibility than a single page of a paper form can offer. Remember that different machines have different color palettes so your users might not see the exact color scheme you design. l It is good practice to: l Add a title to all forms. l Place key data (creation date, originator, folder name) in read-only fields at the top of the form and to place routing/audit data at the bottom of the form. l Design the form to avoid horizontal scrolling. l If possible, try to: l Avoid graphical backgrounds since they increase the time required to load the form. l Avoid large number of different fonts on a form. l Avoid placing labels on top of images. Note: When designing a form using a font which is not available on the deployment service, any references to that font will always be rendered in MS Sans Serif, or equivalent. Creating a Form In most cases, it will be necessary to create one or more forms as part of the process. These forms will be used to collect and/or distribute information. MBPM Designer User's Guide 97 Chapter 20 Designing a Form Forms can be as simple or as complex as required, and may consist of the following: l l l A form background, provided by default (required) Background controls, such as images, frames, and rules, which are used as layout and design controls (optional) Foreground controls, such as buttons, attachment clips, and grids, which are used to collect and display information. In addition to any form controls you chose to add, forms have several predefined properties, which may be changed or reviewed as required through the Properties pane. When using a control on a form that expands when clicked (for example, Date/time control), make sure the form is designed to be big enough to display the control completely at runtime. Note: There is no restriction on the maximum size of a Form. Scrollbars are automatically displayed when size of Form exceeds the screen dimension. Create a New Form To create a new form: 1. On the Home ribbon tab, Components group, click the Form button. You can also create a form using templates or by following the steps below: a. Right-click menu on any item in the Inventory. b. Click New. c. Click Form. A blank form is displayed in a tabbed window in the Designer. You can drag the corners or sides of this form to re-size it. To change the appearance of the form, edit the form properties. Drag and drop the controls in the toolbox to build the form. Note: When a form is created it is not associated to anything. To use the form you must attach one or more processes to it. The Form toolbox is replaced with the process toolbar when you are working on a process. Using the Form Toolbox Form controls are added to forms and form segments via the Form Toolbox. The Form Toolbox is a floating dialog, which you may move or toggle on/off at your convenience. The Form Toolbox will automatically be displayed by default when a form is active in the Designer. To toggle the Toolbox on and off: l Select the View ribbon tab and click on the Toolbox button. The form toolbox is divided into two sections: 98 MBPM Designer User's Guide Chapter 20 Designing a Form l Default The Pointer allows you to select a particular form control or to cancel a select-and-drag action. l Controls The controls that can be added to the form or form segment are listed here. l Business Objects The Business Objects can be used to access and manipulate data in a business process. Using Forms and Form Segments Whenever you are designing a form, the form toolbox will be available. The buttons on the form toolbox are used to add form controls to the form. Open an Existing Form or Form Segment You can open a Form or Form Segment in one of the following ways: l l l In the Inventory, double-click the Form/Form Segment or right-click on Form/Form Segment and click Open. In the Inventory, under the 'Used by Forms' node. When a Form Segment is added to a Form, you can right-click within the Form Segment and click 'Go To' and select the form. Close a Form or Form Segment To close a form or form segment: l In the Inventory, right-click on Form/Form Segment and click Close. Or l Click the 'X' button for the Form/Form Segment tab in main pane of the Designer. Or l Right-click on Form tab in the main pane of Designer and click Close. l Right-click on any other tab in the main pane of Designer and click 'Close other tabs' (Form will be closed together with all other open tabs). Close a Form or Form Segment To close a form or form segment: 1. In the Designer, click on the form’s tab. 2. Click Close in the MBPM menu. If you have changed the object’s definition since last saving it, you are prompted to save it. Editing Form and Form Segment Properties To specify the properties of a form or form segment, click anywhere in the form that is not occupied by a form control. The form name will appear in the Properties pane, together with a list of its properties. You can specify or alter any of the properties in the Properties pane. MBPM Designer User's Guide 99 Chapter 20 Designing a Form Form Component Property Name Description Name Specify a unique name to identify this component. This name is not visible at runtime. Caption Choose a caption for this component. Normally it is the caption that is visible at run-time. Height Specify the height, in pixels, of this component. Width Specify the width of the form, in pixels. Color Choose a background color for the form. Font Choose a font for this form. Font color Choose a font color for this form. Restrict viewing to ... Roles that can view this form. The property will display and allow you to select only the built-in default roles or roles with project scope. To use a dynamic role that makes use of process data, use SelectSQL to query the folder table for the process. Only show Form if When a Form is evaluated at runtime for a stage, if the user has the role and the condition evaluates to true, the Form is displayed. Otherwise, the Form is not displayed. The default value is blank, which is interpreted as "true" for the condition. When user loads form Use this to enter a visual script that is run when the form is loaded. On form load Do this when the form loads. Client extensions The field is included only for backwards compatibility. When user exits form What to do when user submits the form. When form canceled Use this to create a script which is run 100 MBPM Designer User's Guide Chapter 20 Designing a Form Property Name Description when the user cancels the form. On form submission Do this when the form is submitted. Notes Use this to enter any specific notes for anyone using this component within the Designer environment. Form Segment Component Property Name Description Name Specify a unique name to identify this component. This name is not visible at runtime. Form segment Choose which form segment should be shown. Position from top The position (in pixels) of this component, from the top edge of the form. Position from left The position (in pixels) of this component, from the left hand side of the form. Height Specify the height, in pixels, of this component. Width Specify the width, in pixels, of this component. Form segment Choose which form segment should be shown. Anchor Use this to adjust form control behavior on form resizing. There are four available options: Top, Bottom, Left and Right. Form controls will change position and be resized depending on the combination of options selected Dock Specifies whether the control should be docked to the left, right, top, bottom, or fill to the control it is placed on. Visibility depends on Indicates rules for showing the control. Notes Use this to enter any specific notes for MBPM Designer User's Guide 101 Chapter 20 Designing a Form Property Name Description anyone using this component within the Designer environment. Form Controls Form controls are the background and interactive items you can place on a form. You can place any number of form controls on a form. If you place too many controls on a form it will take longer to load and will be less easy to use. Form controls are selected from the Form Toolbox, Controls pane. When you are editing a form, the toolbox should display automatically. Control Type Icon Description Image An image control can be used to place an image onto a form. The image formats supported are *.bmp, *.emf, *.wmf, *.ico, *.jpeg, *.jpg, *.png, and *.gif. Designer will display a blank rectangle until you have specified the location of the image in the Picture property. Status A status control can be used to display whether a specified value is within a safety, warning or danger range. The status control can display a different graphic depending upon state. Label A label control is a text that cannot be changed when viewed at runtime; usually used for titles and headers. Rule A rule control adds lines and frames for presentation purposes. Button A button control is used to perform operations associated with the button when it is clicked on. These must not be confused with the action buttons that are automatically added to a form as a result of the process. Clip An attachment clip control allows the user to attach a file to a folder. Attached files become part of the specific folder. MultiClip A multiclip attachment clip control allows the user to attach multiple files to a folder. Attached files become part of the specific folder. Check Box A check box control is used to record a value that can only be TRUE or FALSE. If the check box is unchecked (the default value) the variable behind the check box is set to FALSE. Checking the box sets it to TRUE. 102 MBPM Designer User's Guide Chapter 20 Designing a Form Control Type Icon Description Number A number control can display Integer (whole numbers) and Real (numbers with decimal places) numbers. The range of values that are accepted can be specified – as well as the number of decimal places used if displaying a Real number. Currency A currency control displays currency values. These are set to display a specified currency type. Date/Time A date/time control is used to input or display dates and/or times. Text A text control can be added to a form using a text box. Text boxes can hold up to 250 characters. If you need to give users more space, use a memo control. Dropdown A drop-down control list allows the selection of a text item from a controlled list where only one item may be chosen. This list can be hard-coded into the form or retrieved from a formula or an external database; or can be a mixture of the two. When hard-coding the list, you may also use name-value pairs, which allow you to associate a user-friendly name to a specific database value. Radio Group A radio group control is used to present a range of options to the user. List A list control is used to allow selection of one or more items. The options are provided in a box with each item on a separate line. The selection of multiple items follows the Windows standard of selection (holding down the Shift key to select adjacent items or the Ctrl key to select non-adjacent items). Panel A Panel control allows you to group Form controls. By grouping Form controls into a Panel control, you can move, hide, or display all the controls on it at once. A Panel control can be placed on a Form, Form Segment, Administration Form, or another Panel control. A Form Segment can also be added to a Panel. Use the cross-arrow on a Panel for moving it. Rich Text A rich text control allows content to be edited, formatted and spellchecked for English, French, and German languages. The control is supplied with a toolbar containing a set of options which provide basic editing functionality such as cut, copy, paste, find and replace, undo/redo etc. It is also possible to export data from the edit area to a PDF file. Person The Person Control allows Process Designers to quickly create MBPM Designer User's Guide 103 Chapter 20 Designing a Form Control Type Icon Description collaborative user interfaces. The person is displayed using a thumbnail*, includes an indicator of the person’s presence*, shows the full name, includes the ability to search for and select a user, send an email to the user, or initiate a live chat* in the context of the current folder. * These items will only appear where MBPM Smart Business Workspace is available. Memo A memo control is used to enter large amounts of text onto a form. When the text entered into this control is more than can be displayed a scroll bar is automatically provided. Signature A signature control enables digital signature of a folder. When the signature is authorized, the signer’s user name and a time stamp are displayed. The authorization mechanism for the signature control is established via the MBPM Administrator utility. For a signature field to incorporate the current user's ID or user name, a text field called "UserID" mapped to a variable must be added to the form. When the signature script runs, the UserID is included in the signature; otherwise the text ‘user’ is added. In addition, the process designer must assign the logged on user's name to the UserID field. Grid A grid control is used to display information from a database (either the MBPM database or an external database) in a column and row format. Scroll bars are automatically displayed when the grid cannot display all the requested information. Note that a table associated with an editable grid must have a primary key. If there is no primary key the grid will just appear as Read-Only. The data within Grid cells will automatically wrap if the data in it is longer than the cell width providing enhanced visibility and readability. Using Form Controls Moving Controls You can move a single control or multiple controls at once. Moving a Single Control 1. In the toolbox, click on the Pointer button . 2. Click on the form control to select it. 104 MBPM Designer User's Guide Chapter 20 Designing a Form 3. Drag it to its new position, or use the cursor control keys to move the control in the required direction. Moving Multiple Controls 1. In the toolbox, click on the Pointer button . To select the controls to be moved either: l l Click on each form controls while holding down the Shift or Ctrl key, or Hold down the mouse button and drag to draw a rectangle around all the form controls to be moved. 2. Click on any of the selected form control and drag it, or use the cursor control keys to move the selected block in the required direction. All of the selected form controls will move together. Copying and Pasting Controls You can copy controls and paste them, either to the same form or report, or into another form or report, that is currently open in another instance of the Designer. To copy one or more controls: 1. Select the control to be copied (use Shift/Ctrl click or left mouse button drag to select multiple controls). 2. On the Home ribbon tab, click Copy. The selected controls are copied to the clipboard. If you are pasting to another form or report, select it in the main pane of the Designer (not necessary if you are copying and pasting within the same form or report). 3. On the Home ribbon tab, click Paste. The contents of the clipboard are pasted into the form or report. It may be necessary to drag the pasted content to ensure it does not overlap existing controls. If pasted controls have the same name as existing controls, they will be renamed by incrementing the digit to the end of the name to the next available number. For example, if you copy a control called Button1 and paste it into the same form, the pasted button will be renamed to Button2. Aligning and Spacing Controls The Designer provides facilities for aligning and spacing controls with each other both horizontally and vertically. You can align form controls: l Individually l In groups MBPM Designer User's Guide 105 Chapter 20 Designing a Form Aligning Individual Controls To align an individual form control with other controls: 1. Click on the control to select it. 2. Holding down the mouse button, drag the control around the main pane of the Designer. As you move the control around, thin horizontal or vertical lines will appear in the main pane of the Designer whenever: l The left side of the control is aligned with the left side of another control l The right side of the control is aligned with the right side of another control l The top of the control is aligned with the top of another control l The bottom of the control is aligned with the bottom of another control Aligning and Spacing Groups of Controls You can align and space a selected group of controls in a form using controls in the Layout tab: l l l l The align controls allow you to align the selected group of controls left, right, top, bottom, center vertically or horizontally. Space Equally equalizes the horizontal or vertical space between each selected control. Increase/Decrease increases or decreases the horizontal or vertical spacing between each selected controls in small increments, while ensuring that they remain equally spaced. Remove removes any horizontal or vertical space between the selected controls. MBPM Designer does not consider captions when it aligns form controls; alignment is based upon the control's data field size and position. You should inspect your form layout to verify that the captions for each form controls appear as desired. Removing Controls You can remove form controls from a form or report using either of the following methods: l Select the desired control and press the DELETE key on your keyboard. l Select the desired control, and click Cut in the Clipboard pane of the Home ribbon tab. l Form controls that are Cut are saved in the clipboard, and may be pasted back onto the same or another form in the process. Form controls that are deleted using the Delete are not stored. However, you may use the Undo option to restore deleted items immediately. Grid controls You cannot bind an image directly to a grid cell. Forms on Web Client In the MBPM Web Client, if the user tries to open a form on a stage that no longer exists or is inaccessible due to the lack of user's permissions, then the first available form, if any, is 106 MBPM Designer User's Guide Chapter 20 Designing a Form displayed. Tab Order and Tab Index Tab order defines the order in which user will move focus from one control to another on a form in the Web Client and Mobile Client using the Tab key. The order is determined by an index. To view the Tab Order using Tab Order from the ribbon: 1. Open a form in Designer. 2. Click Design tab. 3. Click Tab Order. The current index for the controls on the form are displayed. To view the Tab Order using Form Properties: 1. Open a form in Designer. 2. In the form Properties pane, click the value of the Tab Order property of the Form. The current tab order for the controls on the form are displayed. To edit the Tab Order using the ribbon: 1. Open a form in Designer. 2. Click Design tab. 3. Click Tab Order. 4. Click the index of the control that you would like to change. The index changes for the control and the index for all other controls are automatically adjusted. To edit the Tab Order using Form Properties: 1. Open a form in Designer. 2. Ensure that Tab Order is not selected from the ribbon. 3. In the form Properties pane, click the value of the Tab Order property of the Form. 4. Adjust the tab order using the arrow keys. The index changes for the control and the index for all other controls are automatically adjusted. Changes in MBPM v9.2 SR1 From MBPM v9.2 SR1, for newly created solutions, image and label controls also will be assigned a tab index. However, they will take part in the tab order only when their URL property is set. For solutions that are not redeployed after upgrading, the behavior of tab order will not change. Images will not take part in tab order and labels will be assigned a tab index only if it is a URL. MBPM Designer User's Guide 107 Chapter 20 Designing a Form For solutions that are redeployed without making any changes to the tab order, labels with URLs and images with URLs will take part in the tab order. They will get tab index values of 1000 and higher to avoid conflict with existing tab indexes. Editing Form Control Properties The tables listed below describe all the form controls and their properties. Note: The Name property cannot contain illegal characters such as spaces. On entering an illegal character, a validation hint dialog is displayed and the illegal characters are removed from the entered string. Attachment clip Property Name Description Caption Choose a caption for this control. Normally it is the caption that is visible at run-time. Name Specify a unique name to identify this control. This name is not visible at runtime. Position from left The position (in pixels) of this control, from the left hand side of the form. Position from top The position (in pixels) of this control, from the top edge of the form. Anchor Use this to adjust form control behavior on form resizing. There are four available options: Top, Bottom, Left and Right. Form controls will change position and be resized depending on the combination of options selected. Edit only 108 If this option is checked, the Remove and Delete menu options are not available. Once a MBPM Designer User's Guide Chapter 20 Designing a Form Property Name Description document has been uploaded or selected in a single clip, the option Upload and Select will also be unavailable. Visibility depends on Indicates rules for showing the control. When changed Use this to create a visual script that is run when this control has been changed. Default action behavior Specify a default action usage status for this control. Variable Indicate whether you want to specify a calculation or select a Business Object variable. Calculation Specify a calculation to retrieve the parameter value. Business Object Item Select a Business Object variable as the Parameter value. Client extensions The field is included only for backwards compatibility. DMS support Indicate whether this control is intended to support a document management system. Default location Specify a location where the data for this attachment can be found. Field has dependants of its own Check this to indicate that other field(s) on this form is dependent on this field, and it should therefore be updated when any field MBPM Designer User's Guide 109 Chapter 20 Designing a Form Property Name Description marked 'field is dependent on another' is changed. Hint Type in the text you want to use to explain to a user how to use this control. Hint text appears when the use rolls or hovers over the control. Notes Use this to enter any specific notes for anyone using this control within the Designer environment. Note: Visibility dependent fields are not visible until you tab out of the field if mouse is used as input device to enter (paste) data. For example, if you have a button that has "visibility depends on" set to a memo field, when you paste content into the memo field using mouse as the input device, the button is not visible until you move the focus out of the memo field. However, if you are using keyboard as the input device, the command button is visible as soon as you start entering data into the memo field. Checkbox Property Name Description Caption Choose a caption for this control. Normally it is the caption that is visible at run-time. Name Specify a unique name to identify this control. This name is not visible at runtime. Caption alignment Choose the position for the caption of this field above, below, to the left or to the right Position from top The position (in pixels) of this control, from the top edge of the form. 110 MBPM Designer User's Guide Chapter 20 Designing a Form Property Name Description Position from left The position (in pixels) of this control, from the left hand side of the form. Anchor Use this to adjust form control behavior on form resizing. There are four available options: Top, Bottom, Left and Right. Form controls will change position and be resized depending on the combination of options selected. Width Specify the width, in pixels, of this control. Visibility depends on Indicates rules for showing the control. Hint Type in the text you want to use to explain to a user how to use this control. Hint text appears when the use rolls or hovers over the control. Variable Indicate whether you want to specify a calculation or select a Business Object variable. Calculation Specify a calculation to retrieve the parameter value. Business Object Item Select a Business Object variable as the Parameter value. On field entry Do this when the control acquires system focus. On field exit Use this to create a script that is run when the user exits the field. MBPM Designer User's Guide 111 Chapter 20 Designing a Form Property Name Description When changed Use this to create a visual script that is run when this control has been changed. Client extensions The field is included only for backwards compatibility. Default action behavior Specify a default action usage status for this control. Field has dependants of its own Check this to indicate that other field(s) on this form is dependent on this field, and it should therefore be updated when any field marked 'field is dependent on another' is changed. Field is dependent on another Check this if you want this field to be updated when any field marked 'field has dependents of its own' has been changed. Notes Use this to enter any specific notes for anyone using this control within the Designer environment. Command Button Property Name Description Caption Choose a caption for this control. Normally it is the caption that is visible at run-time. Name Specify a unique name to identify this control. This name is not visible at runtime. Position from top The position (in pixels) of this control, from the top 112 MBPM Designer User's Guide Chapter 20 Designing a Form Property Name Description edge of the form Position from left The position (in pixels) of this control, from the left hand side of the form. Anchor Use this to adjust form control behavior on form resizing. There are four available options: Top, Bottom, Left and Right. Form controls will change position and be resized depending on the combination of options selected. Width Specify the width, in pixels, of this control. Height Specify the height, in pixels, of this control. Visibility depends on Indicates rules for showing the control. Default action behavior Specify a default action usage status for this control. Open folder (Folder ID) Choose a specific folder to open when this button is pressed. You can also enter an expression to dynamically choose a particular folder at runtime. When button pressed Use this field to enter a visual script that is run when the button is pressed. Client extensions The field is included only for backwards compatibility. MBPM Designer User's Guide 113 Chapter 20 Designing a Form Property Name Description When button pressed Do this when the button is clicked. Hint Type in the text you want to use to explain to a user how to use this control. Hint text appears when the use rolls or hovers over the control. Button action Choose the type of operation this button will perform when pressed. To set the action that will occur when the button is clicked: Click in the Button Action property and select the action from the drop-down list. l l l l l 114 Cancel Action - Allows you to cancel the form without saving any changes. Client Operation - Uses the Client extension script (defined on the Do This tab) to perform an operation specified by the script. Commit Action Updates the database with any changes made to the form and may move the folder to the next stage. Initiate a process Specify the Process name and the Action name within the process to run in their respective fields. Open existing folder - MBPM Designer User's Guide Chapter 20 Designing a Form Property Name Description Allows you to open a folder created previously by this or another process, as specified in the Open folder field. l Server Operation Uses the When button pressed script (defined on the Do This tab) to perform an operation specified by the script. This is the default action. Action name Once you've chosen a process, choose the action to run in that process. Process name Choose a process that has an action you want to run, when this button is pressed. Notes Use this to enter any specific notes for anyone using this control within the Designer environment. Currency Property Name Description Caption Choose a caption for this control. Normally it is the caption that is visible at run-time. Name Specify a unique name to identify this control. This name is not visible at runtime. Caption alignment Choose the position for the caption of this field - MBPM Designer User's Guide 115 Chapter 20 Designing a Form Property Name Description above, below, to the left or to the right. Position from top The position (in pixels) of this control, from the top edge of the form. Position from left The position (in pixels) of this control, from the left hand side of the form. Anchor Use this to adjust form control behavior on form resizing. There are four available options: Top, Bottom, Left and Right. Form controls will change position and be resized depending on the combination of options selected. Width Specify the width, in pixels, of this control. Minimum enabled Indicate whether or not you want to set a minimum value for this field. This property specifies the minimum value that will be accepted as input into a currency property. In the Minimum enabled property, click on the + button. In the Minimum enabled property, select the check box. In the Minimum property, enter the minimum value that will be accepted. Minimum value 116 Choose a minimum value that this field may have. MBPM Designer User's Guide Chapter 20 Designing a Form Property Name Description Maximum enabled Indicate whether or not you want to set a maximum value for this field. This property specifies the maximum value that will be accepted as input into a currency property. In the Maximum enabled property, click on the + button. In the Maximum enabled property, select the check box. In the Maximum property, enter the maximum value that will be accepted. Currency symbol Choose the currency symbol or code to use on this field. Maximum value Choose a maximum value that this field may have. Symbol position Position of symbol. Negative number style Specify how you want negative currency amounts to be displayed in this field. This property choose the negative number style from the following options: Placing a minus sign before the negative currency number (default). Placing a minus sign after the negative currency number Placing parentheses around the negative currency number. MBPM Designer User's Guide 117 Chapter 20 Designing a Form Property Name Description Visibility depends on Indicates rules for showing the control. Decimal places Specify the number of decimal places that will be shown in this field. Default action behavior Specify a default action usage status for this control. When changed Use this to create a visual script that is run when this control has been changed. Variable Indicate whether you want to specify a calculation or select a Business Object variable. Calculation Specify a calculation to retrieve the parameter value. Business Object Item Select a Business Object variable as the Parameter value. Client extensions The field is included only for backwards compatibility. On field entry Do this when the control acquires system focus. On field exit Use this to create a script that is run when the user exits the field. Hint Type in the text you want to use to explain to a user how to use this control. Hint text appears when the use rolls or hovers over the control. Field has dependants of its own Check this to indicate that other field(s) on this form 118 MBPM Designer User's Guide Chapter 20 Designing a Form Property Name Description is dependent on this field, and it should therefore be updated when any field marked 'field is dependent on another' is changed. Field is dependent on another Check this if you want this field to be updated when any field marked 'field has dependents of its own' has been changed. Notes Use this to enter any specific notes for anyone using this control within the Designer environment. Date/Time Property Name Description Caption Choose a caption for this control. Normally it is the caption that is visible at run-time. Name Specify a unique name to identify this control. This name is not visible at runtime. Caption alignment Choose the position for the caption of this field above, below, to the left or to the right. Position from top The position (in pixels) of this control, from the top edge of the form. Position from left The position (in pixels) of this control, from the left hand side of the form. Anchor Use this to adjust form control behavior on form MBPM Designer User's Guide 119 Chapter 20 Designing a Form Property Name Description resizing. There are four available options: Top, Bottom, Left and Right. Form controls will change position and be resized depending on the combination of options selected. Width Specify the width, in pixels, of this control. Format Choose whether this field should display a date, a time, or both. This property defines whether a Date/Time control should display only a date portion, only a time portion, or both a date and a time portion. Earliest Use this to define the earliest value that can be entered in this field. The earliest value that you can enter is 1 January, 1753. If omitted, no specific earliest Date/Time will be enforced. This property is only shown for Date/Time properties that include a date portion ('Date' or 'Both', but not 'Time'). Latest Choose the latest date and/or time that can be shown in this control. This property specifies the latest date that will be accepted as input into a Date/Time property. If omitted, no specific latest Date/Time will be enforced. This property is 120 MBPM Designer User's Guide Chapter 20 Designing a Form Property Name Description only shown for date/time properties that include a date portion ('Date' or 'Both', but not 'Time'). Visibility depends on Indicates rules for showing the control. Disable timezone adjustment Choose whether or not to disable time zone adjustment for this control. When changed Use this to create a visual script that is run when this control has been changed. Default action behavior Specify a default action usage status for this control. Variable Indicate whether you want to specify a calculation or select a Business Object variable. Calculation Specify a calculation to retrieve the parameter value. Business Object Item Select a Business Object variable as the Parameter value. Client extensions The field is included only for backwards compatibility. On field entry Do this when the control acquires system focus. On field exit Use this to create a script that is run when the user exits the field. Hint Type in the text you want to use to explain to a user how to use this control. MBPM Designer User's Guide 121 Chapter 20 Designing a Form Property Name Description Hint text appears when the use rolls or hovers over the control. Field is dependent on another Check this if you want this field to be updated when any field marked 'field has dependents of its own' has been changed. Field has dependants of its own Check this to indicate that other field(s) on this form is dependent on this field, and it should therefore be updated when any field marked 'field is dependent on another' is changed. Notes Use this to enter any specific notes for anyone using this control within the Designer environment. Note: To enter static date for Earliest/Latest/Default value in a calculation, use quotes around the value. For example, "12/03/1983". Otherwise, date will be evaluated as a division expression, calculated, and converted to date. Dropdown Property Name Description Caption Choose a caption for this control. Normally it is the caption that is visible at runtime. Name Specify a unique name to identify this control. This name is not visible at run-time. Caption alignment Choose the position for the caption of this field - above, below, to the left or to the right. Position from top The position (in pixels) of this control, from the top edge of the form. 122 MBPM Designer User's Guide Chapter 20 Designing a Form Property Name Description Position from left The position (in pixels) of this control, from the left hand side of the form. Anchor Use this to adjust form control behavior on form resizing. There are four available options: Top, Bottom, Left and Right. Form controls will change position and be resized depending on the combination of options selected. Width Specify the width, in pixels, of this control. List options Click here to define the options that appear in the dropdown. Click on the ellipsis button to the right of the property value. The List Options dialog is displayed. The list option picker allows the user to create a list from three types: l From an expression which returns a list of values l From a Business Object l From a SELECT statement From an expression which returns a list of values To create an expression, you can type in values directly in the bottom pane. For example, you can type: "A", "B", "C" and click OK. The static list is displayed at runtime. You can also use the Expression Builder to populate the list of values. The ListFunctionsLibrary provides functions that facilitate MBPM Designer User's Guide 123 Chapter 20 Designing a Form Property Name Description returning a list that can be used to populate the List options value. The ListFunctionsLibrary.Solution is available in the following location: C:\Program Files\Metastorm\BPM\Sample Processes\ListConversionLibrary For more information, see Using List Functions Library From a Business Object Choose a Business Object from the list of Business Objects that you have created. Depending on the chosen Business Object, you can select a 1-column list of values or a list of name-value pairs. You can use a Name/Value pair to give a meaningful name to a database value. For example, you can use “High Priority” as the name for value of “1” in the database. For Name/Value pair, two rows are displayed: l Name l Value From a SELECT statement Select a connection from the Connection drop-down list. For the SQL Syntax, you can either type in the SELECT statement or display the Query Builder to construct the query. Visibility depends on Indicates rules for showing the control. Default action behavior Specify a default action usage 124 MBPM Designer User's Guide Chapter 20 Designing a Form Property Name Description status for this control. When changed Use this to create a visual script that is run when this control has been changed. Variable Indicate whether you want to specify a calculation or select a Business Object variable Calculation Specify a calculation to retrieve the parameter value. Business Object Item Select a Business Object variable as the Parameter value. Client extensions The field is included only for backwards compatibility. On field entry Do this when the control acquires system focus On field exit Use this to create a script that is run when the user exits the field. Field is dependent on another Check this if you want this field to be updated when any field marked 'field has dependents of its own' has been changed. Field has dependants of its own Check this to indicate that other fields on this form are dependent on this field, and it should therefore be updated when any field marked 'field is dependent on another' is changed. Hint Type in the text you want to use to explain to a user how to use this control. Hint text appears when the use rolls or hovers over the control. Notes Use this to enter any specific notes for anyone using this MBPM Designer User's Guide 125 Chapter 20 Designing a Form Property Name Description control within the Designer environment. Grid Property Name Description Name Specify a unique name to identify this control. This name is not visible at run-time. Width Specify the width, in pixels, of this control. Height Specify the height, in pixels, of this control. Position from top The position (in pixels) of this control, from the top edge of the form. Position from left The position (in pixels) of this control, from the left hand side of the form. Business Object Select the Business Object to be used to retrieve the grid's data. Columns Use this option to manage the columns that will appear on your grid. Grids are used on forms and report bands. A grid maps multiple rows and columns (fields) from one or more database tables. You can place any number of grids on a form. Grids will overlay any background (image, rule, or label) controls. Grids do not support paging on Business Object's CurrentIndex. Columns This property is used to build the grid by adding and removing columns. 126 MBPM Designer User's Guide Chapter 20 Designing a Form Property Name Description 1. In the Columns property, click on the ellipsis button. The Columns builder is displayed with one default column. 2. To add another column, click on the Add button. A new column is added to the left pane. Column types available are: l l l l l l l l l MBPM Designer User's Guide Text: A text column type is added. Currency: A currency column type is added. Date and Time: A date and type column type is added. Number: A number column type is added. Drop-down: A drop-down column type is added. Folder: If you choose the “Folder” as column type, then the values of the selected Business Object Item are FolderIDs. At runtime, the contents of this column will contain hyperlinks to these folders. Also, on the Web Client, the display value of a folder column will be “Open folder”, and it is hyperlinked to open the folder of the underlying FolderID. Status: A Status column type is added. Person: A Person column type is added. Hyperlink: A hyperlink column type is added. Note that some browsers have problems with URLs containing spaces. If you experience such problems, replace each space with %20. 127 Chapter 20 Designing a Form Property Name Description Business Object Item The Business Object Item property displays variables of type Int, Real, Text and Memo. Default action The Folder Column can have default action usage set to either “ReadOnly” or “Hidden”. In V7.6 only one column could be set to be a folder column, but in V9, more than one column can be set to be a folder column. Folder Columns will not be available for editable grids. Status: If you choose "Status" as column type, you can set the following properties for the column: Property Name Description Safety threshold Use this field to specify the value of the safety threshold for this status field. Danger threshold Use this field to specify the value of the danger threshold for this status field. Value as Use percentages percentages for threshold values. 100% 128 Enter a value that represents "100%" for this status. (For example if you have 1,300 staff, MBPM Designer User's Guide Chapter 20 Designing a Form Property Name Description enter '1,300' in this field.) Display value Allows both the icon and value to be displayed. Alignment value Set the alignment of value to the left, right, top, or bottom for Status fields. Set the alignment of value to the left or right for Status Fields in Grids and Custom Lists. Drill down to Choose whether this status field drills down to one of the following: 1. No drill down No drill down is performed. 2. Initiate a Process Selecting this option displays the Dynamic, Process, Action, and Parameters fields. If you do not select Dynamic, you can select the static values for the Process and Actions available in the selected process from the respective drop- MBPM Designer User's Guide 129 Chapter 20 Designing a Form Property Name Description down lists. If you select Dynamic, you can click on the Expression Builder icon in the Process and Action fields to set the respective values. The Parameters field is displayed when static values are set for the Process and Action fields. The Parameters value can be set by clicking on the ellipsis button. The Expression Builder with Assignments Builder is launched where you can set the values to the form fields. 3. Administration form Selecting this option displays the Dynamic, Administration Form Group, Administration Form, and Parameters fields. If you do not select Dynamic, you can select the 130 MBPM Designer User's Guide Chapter 20 Designing a Form Property Name Description static values for the Administration Form Group and Administration Form from the respective dropdown lists. If you select Dynamic, you can click on the Expression Builder icon in the Administration Form Group and Administration Form fields to set the respective values. The Parameters field is displayed when static values are set for the Administration Form Group and Administration Form fields. The Parameters value can be set by clicking on the ellipsis button. The Expression Builder with Assignments Builder is launched where you can set the values to the form fields. 4. URL Enter a URL to open when this status button is MBPM Designer User's Guide 131 Chapter 20 Designing a Form Property Name Description clicked on. 5. Existing Folder Selecting this option displays two sub-fields: - FolderID - FolderID Reference Type On selecting FolderID Reference Type, two options are displayed: "Text" and "Business Object". Selecting "Text" causes Folder ID to become a static text field. If "Business Object" is selected, a list of Business Object text variables is displayed in the FolderID field, allowing selection of one of these variables to be bound to the Grid or Custom List. clicked on. 132 Warning Choose an image to display if this status state becomes a warning. Warning hint When deployed, the text entered is displayed as an MBPM Designer User's Guide Chapter 20 Designing a Form Property Name Description alternative text when you hover your mouse over the field. MBPM Designer User's Guide Safety Choose an image to display if this status state becomes a safety. Safety hint When deployed, the text entered is displayed as an alternative text when you hover your mouse over the field. Danger Choose an image to display if this status state becomes a danger. Danger hint When deployed, the text entered is displayed as an alternative text when you hover your mouse over the field. Width Choose the width for the column Default action behavior Choose from displaying the column as readonly data, hidden column, optional, or required. The ‘optional’ and ‘required’ options are for editable grids only. 133 Chapter 20 Designing a Form Property Name Description Default Value Calculation Business Object Item Choose Calculated or Business Object. If ‘Calculated’ is selected, the subproperty ‘Calculation’ is displayed. If ‘Business Object’ is selected, the sub-property ‘Business Object Item’ is displayed. Specify a calculation to retrieve a parameter value. Select a Business Object variable as the Parameter value. l Hyperlink If you choose "Hyperlink" as column type, you can select a Business Object Item consisting of url values. These Business Object items can be of the text or memo data type. You can select a Business Object variable as the display value for the selected url. By default, the display value will point to the same Business Object Item value as selected in the Business Object Item property. In the Web Client, the “Display values” are displayed as hyperlinked text that will link to the underlying URL value (as selected 134 MBPM Designer User's Guide Chapter 20 Designing a Form Property Name Description by the Business Object Item property). Default action usage Default action usage set to either “Read-Only” or “Hidden”. Person: A person column type is added: If you choose "Person" as column type, you can select the "Name" option to display further information about the person. To set the column details, select the column in the left pane and then edit it in the right pane. To change the order of a column in the grid, select the column and use the arrow keys to move it up or down. To remove a column from the grid. Select the column in the right pane and click on the Remove button. Enable Client-side Paging Client-side paging is available to grids bound to either editable Business Objects or read-only Business Objects. The default size of the client-side page is 50. If no server side paging has been specified, you will be able to enter any value as the client side page size. If the client-side paging has been enabled, then the client-side grid will only contain as many rows as specified by the client-side page size. Further pages will then be accessed using navigational controls of the grid available at runtime. If server side paging is specified, then the client-side page size must MBPM Designer User's Guide 135 Chapter 20 Designing a Form Property Name Description be an exact fraction of the serverside page size. For example, if the server-side page size is set to be 100, then the client side page size can be 1, 2, 5, 10, 20, 50, or 100. This ensures that partial results from a server side page are not displayed within a client-side page. Visibility depends on Indicates rules for showing the control. Column sizing units Use this option to specify units for column width size. It can have two values: Percent and Pixels. If you use Pixels, columns are not resized when Grid is resized. However, you can change column width by dragging the column borders. If you use Percent, 'Width' property for columns is re-calculated taking the whole Grid width as 100%. Columns are resized keeping your set proportions when a Grid is resized. You can also change column width by dragging the column borders. Default is Pixels. Default action behavior Specify a default action usage status for this control. On cell entry Use this to create a script that is run when the user enters the cell. On cell exit Use this to create a script that is run when the user exits the cell. When user selects row Do this when the user selects a row. Client extensions The field is included only for backwards compatibility. Field has dependants of its Check this to indicate that other 136 MBPM Designer User's Guide Chapter 20 Designing a Form Property Name Description own field(s) on this form is dependent on this field, and it should therefore be updated when any field marked 'field is dependent on another' is changed. Field is dependent on another Check this if you want this field to be updated when any field marked 'field has dependents of its own' has been changed. Read-only Used to specify that the grid should be rendered as read-only when the Business Object attached to the grid is read-write. Hint Type in the text you want to use to explain to a user how to use this control. Hint text appears when the use rolls or hovers over the control. Notes Use this to enter any specific notes for anyone using this control within the Designer environment. Keep in mind the following when working with grid controls: l l If you create a Grid with several columns and assign the same Business Object variable to all the columns, the Web Client displays the Grid with data only in the first column and all other columns of the Grid will be empty. In some instances, the following error is displayed when opening the Form: “An item with the same key has already been added.” As a result of this limitation, MBPM does not support using the same Business Object variable in multiple columns of a Grid. For example, consider a Grid has multiple columns (col1, col2, col3, and so on) and Business Object with variables var1, var2, and so on. Using the Properties pane of the Grid, assign var1 to col1 of the Grid, then assign var1 to col2 of the Grid, and then the same var1 to col3 of the Grid. In the Web Client, data is shown only in col1 of the Grid and remaining columns (col2 and col3) are empty. Data is not displayed in all columns of the Grid. A table associated with an editable grid must have a primary key. If there is no primary key the grid will just appear as Read-Only. Image Property Name Description Name Specify a unique name to MBPM Designer User's Guide 137 Chapter 20 Designing a Form Property Name Description identify this control. This name is not visible at runtime. Position from top The position (in pixels) of this control, from the top edge of the form. Position from left The position (in pixels) of this control, from the left hand side of the form. Anchor Use this to adjust form control behavior on form resizing. There are four available options: Top, Bottom, Left and Right. Form controls will change position and be resized depending on the combination of options selected. Picture Choose a graphic for this image control. Width Specify the width, in pixels, of this control. Height Specify the height, in pixels, of this control. URL Enter a URL that should be displayed when this image is clicked on. Visibility depends on Indicates rules for showing the control. Client extensions The field is included only for backwards compatibility. Notes Use this to enter any specific notes for anyone using this control within the Designer environment. 138 MBPM Designer User's Guide Chapter 20 Designing a Form Label Property Name Description Caption Choose a caption for this control. Normally it is the caption that is visible at run-time. Name Specify a unique name to identify this control. This name is not visible at runtime. Caption type Available options are Static and Calculated. If ‘static’ is chosen, the current caption property is displayed. If ‘dynamic’ is chosen, an expression property is displayed. Note that the expressions are not evaluated. Field Alignment Choose an alignment (left, center or right) for the label's text. Position from top The position (in pixels) of this control, from the top edge of the form. Position from left The position (in pixels) of this control, from the left hand side of the form. Anchor Use this to adjust form control behavior on form resizing. There are four available options: Top, Bottom, Left and Right. Form controls will change position and be resized depending on the combination of options selected. MBPM Designer User's Guide 139 Chapter 20 Designing a Form Property Name Description Width Specify the width, in pixels, of this control. Height Specify the height, in pixels, of this control. Font Choose a font for this label. Font Color Choose a font color for this label. URL Enter a URL to display when this label is clicked on. Visibility depends on Indicates rules for showing the control. Client extensions The field is included only for backwards compatibility. Notes Use this to enter any specific notes for anyone using this control within the Designer environment. Using dynamic URL for Label To use a dynamic URL for Label: 1. Create 2 textboxes: Name, URL 2. Right-click and choose Add Variable to assign local Business Object text variables for the textboxes. For example: Local.Name and Local.URL 3. For both text boxes, enable the following properties: l Field is dependent on another l Field has dependents of its own 4. Create 2 labels: LabelSiteName, LabelSiteURL 5. For both labels, enable the following properties: l Change Caption Type to Calculated l Select Field is dependent on another 6. For LabelSiteName, in the Caption field, enter an expression: 140 MBPM Designer User's Guide Chapter 20 Designing a Form l Local.Name 7. For LabelSiteURL, in the Caption field, enter an expression: l "<a href=" + Local.URL + ">" + Local.Name + "</a>" 8. Deploy the project. Enter different values in the Name and URL text boxes and observe that the corresponding labels and the associated URL are changed dynamically. List Property Name Description Caption Choose a caption for this control. Normally it is the caption that is visible at runtime. Name Specify a unique name to identify this control. This name is not visible at run-time. Caption alignment Choose the position for the caption of this field - above, below, to the left or to the right. Position from top The position (in pixels) of this control, from the top edge of the form. Position from left The position (in pixels) of this control, from the left hand side of the form. Anchor Use this to adjust form control behavior on form resizing. There are four available options: Top, Bottom, Left and Right. Form controls will change position and be resized depending on the combination of options selected. Width Specify the width, in pixels, of this control. Height Specify the height, in pixels, of MBPM Designer User's Guide 141 Chapter 20 Designing a Form Property Name Description this control. Visibility depends on Indicates rules for showing the control. Default action behavior Specify a default action usage status for this control. When changed Use this to create a visual script that is run when this control has been changed. Variable Indicate whether you want to specify a calculation or select a Business Object variable. Calculation Specify a calculation to retrieve the parameter value. Business Object Item Select a Business Object variable as the Parameter value. Client extensions The field is included only for backwards compatibility. On field entry Do this when the control acquires system focus. On field exit Use this to create a script that is run when the user exits the field. List options Click here to define the options that appear in this list. Click on the ellipsis button to the right of the property value. The List Options dialog is displayed. The list option picker allows the user to create a list from three types: l 142 From an expression which returns a list of values l From a Business Object l From a SELECT statement MBPM Designer User's Guide Chapter 20 Designing a Form Property Name Description From an expression which returns a list of values To create an expression, you can type in values directly in the bottom pane. For example, you can type: "A", "B", "C" and click OK. The static list is displayed at runtime. You can also use the Expression Builder to populate the list of values. The ListFunctionsLibrary provides functions that facilitate returning a list that can be used to populate the List options value. The ListFunctionsLibrary.Solution is available in the following location: C:\Program Files\Metastorm\BPM\Sample Processes\ListConversionLibrary For more information, see Using List Functions Library From a Business Object Choose a Business Object from the list of Business Objects that you have created. Depending on the chosen Business Object, you can select a 1-column list of values or a list of name-value pairs. You can use a name/value pair to give a meaningful name to a database value. For example, you can use “High Priority” as the name for value of “1” in the database. For name/value pair, two rows are displayed: l MBPM Designer User's Guide Name 143 Chapter 20 Designing a Form Property Name Description l Value From a SELECT statement Select a connection from the Connection drop-down list. For the SQL Syntax, you can either type in the SELECT statement or display the Query Builder to construct the query. Field is dependent on another Check this if you want this field to be updated when any field marked 'field has dependents of its own' has been changed. Field has dependants of its own Check this to indicate that other field(s) on this form is dependent on this field, and it should therefore be updated when any field marked 'field is dependent on another' is changed. Hint Type in the text you want to use to explain to a user how to use this control. Hint text appears when the use rolls or hovers over the control. Notes Use this to enter any specific notes for anyone using this control within the Designer environment. Memo Property Name Description Caption Choose a caption for this control. Normally it is the caption that is visible at run-time. Name Specify a unique name to identify this control. This name is not visible at run- 144 MBPM Designer User's Guide Chapter 20 Designing a Form Property Name Description time. Caption alignment Choose the position for the caption of this field above, below, to the left or to the right. Position from top The position (in pixels) of this control, from the top edge of the form. Position from left The position (in pixels) of this control, from the left hand side of the form. Anchor Use this to adjust form control behavior on form resizing. There are four available options: Top, Bottom, Left and Right. Form controls will change position and be resized depending on the combination of options selected. Width Specify the width, in pixels, of this control. Height Specify the height, in pixels, of this control. Visibility depends on Indicates rules for showing the control. When changed Use this to create a visual script that is run when this control has been changed. Default action behavior Specify a default action usage status for this control. Variable Indicate whether you want to specify a calculation or select a Business Object variable. MBPM Designer User's Guide 145 Chapter 20 Designing a Form Property Name Description Calculation Specify a calculation to retrieve the parameter value. Business Object Item Select a Business Object variable as the Parameter value. Client extensions The field is included only for backwards compatibility. On field entry Do this when the control acquires system focus. On field exit Use this to create a script that is run when the user exits the field. Field has dependants of its own Check this to indicate that other field(s) on this form is dependent on this field, and it should therefore be updated when any field marked 'field is dependent on another' is changed. Field is dependent on another Check this if you want this field to be updated when any field marked 'field has dependents of its own' has been changed. Hint Type in the text you want to use to explain to a user how to use this control. Hint text appears when the use rolls or hovers over the control. Notes Use this to enter any specific notes for anyone using this control within the Designer environment. 146 MBPM Designer User's Guide Chapter 20 Designing a Form Multi-clip Property Name Description Name Specify a unique name to identify this control. This name is not visible at runtime. Position from top The position (in pixels) of this control, from the top edge of the form. Position from left The position (in pixels) of this control, from the left hand side of the form. Width Specify the width, in pixels, of this control. Height Specify the height, in pixels, of this control. Edit only If this option is checked, the Remove and Delete menu options are not available to the Process User. Once a document has been uploaded or selected in a single clip, the option Upload and Select will also be unavailable. Client extensions The field is included only for backwards compatibility. Default action behavior Specify a default action usage status for this control. Visibility depends on Indicates rules for showing the control. Field has dependants of its own Check this to indicate that other field(s) on this form is dependent on this field, and it should therefore be MBPM Designer User's Guide 147 Chapter 20 Designing a Form Property Name Description updated when any field marked 'field is dependent on another' is changed. Default location Specify a location where the data for this attachment can be found. DMS support Indicate whether this control is intended to support a document management system. Hint Type in the text you want to use to explain to a user how to use this control. Hint text appears when the use rolls or hovers over the control. Notes Use this to enter any specific notes for anyone using this control within the Designer environment. Note: Multiclip and DMS Multiclip control's columns are resized proportionally to whole control width when you resize a Form. Number Property Name Description Caption Choose a caption for this control. Normally it is the caption that is visible at run-time. Name Specify a unique name to identify this control. This name is not visible at runtime. Caption alignment Choose the position for the caption of this field above, below, to the left or to the right. 148 MBPM Designer User's Guide Chapter 20 Designing a Form Property Name Description Position from top The position (in pixels) of this control, from the top edge of the form. Position from left The position (in pixels) of this control, from the left hand side of the form. Anchor Use this to adjust form control behavior on form resizing. There are four available options: Top, Bottom, Left and Right. Form controls will change position and be resized depending on the combination of options selected. Width Specify the width, in pixels, of this control Minimum enabled Indicate whether or not you want to set a minimum value for this field. This property specifies the minimum value that will be accepted as input into a number property. 1. In the Minimum enabled property, click on the + button. 2. In the Minimum enabled property, select the check box. 3. In the Minimum property, enter the minimum value that will be accepted. l MBPM Designer User's Guide You cannot set a Maximum value lower than a Minimum value. For example, if you set 149 Chapter 20 Designing a Form Property Name Description the Minimum option to 10, the lowest possible Maximum value will automatically be set to 10. l In addition, even though valid maximum and minimum values have been set, if the number property is an optional field on a form, the user may leave the field blank and still have the property pass validation. If the values set in the Properties editor are required minimum/maximum values, the property must be made a required property on the form. Minimum value Choose a minimum value that this field may have. Maximum enabled Indicate whether or not you want to set a maximum value for this field. This property specifies the maximum value that will be accepted as input into a number property. 1. In the Maximum enabled property, click on the + button. 2. In the Maximum enabled property, select the check box. 3. In the Maximum 150 MBPM Designer User's Guide Chapter 20 Designing a Form Property Name Description property, enter the maximum value that will be accepted. Maximum value Choose a maximum value that this field may have. Visibility depends on Indicates rules for showing the control. Decimal places Specify the number of decimal places that will be shown in this field. Client extensions The field is included only for backwards compatibility. Variable Indicate whether you want to specify a calculation or select a Business Object variable. Calculation Specify a calculation to retrieve the parameter value. Business Object Item Select a Business Object variable as the Parameter value. Default action behavior Specify a default action usage status for this control. When changed Use this to create a visual script that is run when this control has been changed. On field exit Use this to create a script that is run when the user exits the field. On field entry Do this when the control acquires system focus. Field is dependent on another Check this if you want this field to be updated when MBPM Designer User's Guide 151 Chapter 20 Designing a Form Property Name Description any field marked 'field has dependents of its own' has been changed. Field has dependants of its own Check this to indicate that other field(s) on this form is dependent on this field, and it should therefore be updated when any field marked 'field is dependent on another' is changed. Hint Type in the text you want to use to explain to a user how to use this control. Hint text appears when the use rolls or hovers over the control. Notes Use this to enter any specific notes for anyone using this control within the Designer environment. Note: If a number field is set to required, 0 (zero) is not an acceptable value. Panel Property Name Description Name Specify a unique name to identify this control. This name is not visible at runtime. Position from top The position (in pixels) of this control, from the top edge of the form. Position from left The position (in pixels) of this control, from the left hand side of the form. Height Specify the height, in pixels, of this control. Width Specify the width, in 152 MBPM Designer User's Guide Chapter 20 Designing a Form Property Name Description pixels, of this control. Color Choose a color for this control. Anchor Use this to adjust form control behavior on form resizing. There are four available options: Top, Bottom, Left and Right. Form controls will change position and be resized depending on the combination of options selected. Dock Relative to the Form, you can dock the Panel either to the Top, Bottom, Left, or Right. Use Fill to make the Panel take up the entire Form control area. Visibility Indicates rules for showing the control. Tab Order Determines the order in which user will move focus from one control to another using the TAB key. Notes Use this to enter any specific notes for anyone using this control within the Designer environment. Behavior of the Panel with docking set to 'Fill' depends on its z-order. The Panel will fill all space on Form except those which is already taken by Panels created earlier. All Panels created after the Panel with ‘Fill’ docking will be placed over it. Person Property Name Description Caption Choose a caption for this control. Normally it is the caption that is visible at MBPM Designer User's Guide 153 Chapter 20 Designing a Form Property Name Description run-time. Name Specify a unique name to identify this control. This name is not visible at runtime. Position from top The position (in pixels) of this control, from the top edge of the form. Position from left The position (in pixels) of this control, from the left hand side of the form. Anchor Use this to adjust form control behavior on form resizing. There are four available options: Top, Bottom, Left and Right. Form controls will change position and be resized depending on the combination of options selected. Visibility depends on Indicates rules for showing the control. User Name Indicate whether you want to specify a calculation or select a Business Object variable. Calculation Specify a calculation to retrieve the parameter value. Business Object Item Select a Business Object variable as the Parameter value. Default action behavior Specify a default action usage status for this control. Field is dependent on another Check this if you want this 154 MBPM Designer User's Guide Chapter 20 Designing a Form Property Name Description field to be updated when any field marked 'field has dependents of its own' has been changed. Field has dependants of its own Check this to indicate that other fields on this form are dependent on this field, and it should therefore be updated when any field marked 'field is dependent on another' is changed. Hint Type in the text you want to use to explain to a user how to use this control. Hint text appears when the use rolls or hovers over the control. Notes Use this to enter any specific notes for anyone using this control within the Designer environment. Rich Text Property Name Description Caption Choose a caption for this control. Normally it is the caption that is visible at run-time. Name Specify a unique name to identify this control. This name is not visible at runtime. Caption alignment Choose the position for the caption of this field above, below, to the left or to the right. Position from top The position (in pixels) of MBPM Designer User's Guide 155 Chapter 20 Designing a Form Property Name Description this control, from the top edge of the form. Position from left The position (in pixels) of this control, from the left hand side of the form. Anchor Use this to adjust form control behavior on form resizing. There are four available options: Top, Bottom, Left and Right. Form controls will change position and be resized depending on the combination of options selected. Width Specify the width, in pixels, of this control. Height Specify the width, in pixels, of this control. Visibility depends on Indicates rules for showing the control. Default action behavior Specify a default action usage status for this control. Variable Indicate whether you want to specify a calculation or select a Business Object variable. Calculation Specify a calculation to retrieve the parameter value. Business Object Item Select a Business Object variable as the Parameter value. Auto-hide Check this to ensure that the toolbar is always displayed. Uncheck to 156 MBPM Designer User's Guide Chapter 20 Designing a Form Property Name Description display the toolbar only when the control is being edited. Client extensions The field is included only for backwards compatibility. On field entry Do this when the control acquires system focus. On field exit Use this to create a script that is run when the user exits the field. Field is dependent on another Check this if you want this field to be updated when any field marked 'field has dependents of its own' has been changed. Field has dependants of its own Check this to indicate that other fields on this form are dependent on this field, and it should therefore be updated when any field marked 'field is dependent on another' is changed. Hint Type in the text you want to use to explain to a user how to use this control. Hint text appears when the use rolls or hovers over the control. Notes Use this to enter any specific notes for anyone using this control within the Designer environment. Rich Text spell-check supports only following languages: l English (United States) [en-US] l French (France) [fr-FR] MBPM Designer User's Guide 157 Chapter 20 Designing a Form l German (Germany) [de-DE] To send Rich Text contents as an e-mail: 1. Add a Rich Text control and a Command button to a Form. 2. Assign a text variable named RTV to the Rich Text control. Set name of the Button to btnSendEmail. 3. Select 'Server operation' in Button Activity property for the btnSendEmail. 4. Add Event Handler Script to 'On Button Pressed' action. 5. Add Code Activity to Event Handler. 6. Add the following line to code function body: Mstm.SendEmail("to@email","cc@email","CC",Local.RTV ,"",""); Replace to@email and cc@email with your own email address. Note: Email address with non-ascii characters is not supported by SendEmail. Following are the examples of email addresses which are not supported: 伊昭傑 @郵件 .商務 (Chinese, Unicode) юзер@екзампл.ком (Ukrainian, Unicode) θσερ@εχαμπλε.ψομ (Greek, Unicode) 7. Deploy the Solution. 8. Open the relevant Form from the Blank Forms in the Web Client. 9. Form opens with Rich Text control and btnSendEmail. 10. Type some text with different formatting (size, color, font, background color, italic, bold, etc) in Rich Text control. 11. Press btnSendEmail. 12. Check your e-mail. Observe the e-mail content. It should have the same formatting that it has in Rich Text control. To convert Rich Text control’s formatted content to a Text control’s unformatted content: 1. Using the Form from the previous example, create the following additional controls: A Text control named PlainText and a Command button named PlainTextEmail. 2. Select 'Server operation' in Button Activity property for the PlainTextEmail. 3. Add Event Handler Script to PlainTextEmail’s ‘On Button Pressed' action. 4. Add Code Activity to Event Handler. 5. Add the following line to code function body: Local.PlainText = Mstm.HtmlToText(Local.RTV); Mstm.SendEmail("to@email","cc@email","CC",Local.PlainText ,"",""); Replace to@email and cc@email with your own email address. Note: Email address with non-ASCII characters is not supported by SendEmail. 158 MBPM Designer User's Guide Chapter 20 Designing a Form 6. Deploy the Solution. 7. Open the relevant Form from the Blank Forms in the Web Client. 8. Type some text with different formatting (size, color, font, background color, italic, bold, etc) in Rich Text control. 9. Press PlainTextEmail. 10. Check your e-mail. Observe the e-mail content. It should not have any formatting as we have removed the formatting by copying the contents from Rich Text control to a Text control using the HtmlToText function. Radio group Property Name Description Caption Choose a caption for this control. Normally it is the caption that is visible at run-time. Name Specify a unique name to identify this control. This name is not visible at runtime. Position from top The position (in pixels) of this control, from the top edge of the form. Position from left The position (in pixels) of this control, from the left hand side of the form. Anchor Use this to adjust form control behavior on form resizing. There are four available options: Top, Bottom, Left and Right. Form controls will change position and be resized depending on the combination of options selected. Width Specify the width, in pixels, of this control. Height Specify the height, in pixels, of this control. MBPM Designer User's Guide 159 Chapter 20 Designing a Form Property Name Description Orientation Choose whether you want to display this radio group horizontally, rather than vertically, that is the default. Visibility depends on Indicates rules for showing the control. When changed Use this to create a visual script that is run when this control has been changed. Default action behavior Specify a default action usage status for this control. Variable Indicate whether you want to specify a calculation or select a Business Object variable. Calculation Specify a calculation to retrieve the parameter value. Business Object Item Select a Business Object variable as the Parameter value. Client extensions The field is included only for backwards compatibility. On field entry Do this when the control acquires system focus. Note: The On field entry event occurs when moving between radio groups and other controls and not when moving between radio buttons within a radio group. On field exit 160 Use this to create a script that is run when the user exits the field. MBPM Designer User's Guide Chapter 20 Designing a Form Property Name Description Note: The On field exit event occurs when moving between radio groups and other controls and not when moving between radio buttons within a radio group. Radio button captions This specifies the caption to be displayed against each individual button in a radio group, and to be stored in the radio group’s variable when a button is selected. l l l In the drop-down menu, select an Option caption and type the caption you want. To display more than three buttons, in the drop-down menu, click after the last caption and press Return to start a new line. To delete a radio button, in the dropdown menu, select the caption and press DELETE key. Field is dependent on another Check this if you want this field to be updated when any field marked 'field has dependents of its own' has been changed. Field has dependants of its own Check this to indicate that other fields on this form are dependent on this field, and it should therefore be updated when any field marked 'field is dependent on another' is changed. MBPM Designer User's Guide 161 Chapter 20 Designing a Form Property Name Description Hint Type in the text you want to use to explain to a user how to use this control. Hint text appears when the use rolls or hovers over the control. Notes Use this to enter any specific notes for anyone using this control within the Designer environment. Rule Property Name Description Name Specify a unique name to identify this control. This name is not visible at runtime. Position from left The position (in pixels) of this control, from the left hand side of the form. Position from top The position (in pixels) of this control, from the top edge of the form. Anchor Use this to adjust form control behavior on form resizing. There are four available options: Top, Bottom, Left and Right. Form controls will change position and be resized depending on the combination of options selected. Width Specify the width, in pixels, of this control. Height Specify the height, in pixels, of this control. 162 MBPM Designer User's Guide Chapter 20 Designing a Form Property Name Description Type Rule type. Color Choose a color for this line or box. Style Style for the rule. Client extensions The field is included only for backwards compatibility. Visibility depends on Indicates rules for showing the control. Notes Use this to enter any specific notes for anyone using this control within the Designer environment. Signature Property Name Description Caption Choose a caption for this control. Normally it is the caption that is visible at run-time. Name Specify a unique name to identify this control. This name is not visible at runtime. Caption alignment Choose the position for the caption of this field above, below, to the left or to the right. Position from top The position (in pixels) of this control, from the top edge of the form. Position from left The position (in pixels) of this control, from the left hand side of the form. Anchor Use this to adjust form MBPM Designer User's Guide 163 Chapter 20 Designing a Form Property Name Description control behavior on form resizing. There are four available options: Top, Bottom, Left and Right. Form controls will change position and be resized depending on the combination of options selected. Width Specify the width, in pixels, of this control. Height Specify the height, in pixels, of this control. Visibility depends on Indicates rules for showing the control. Default action behavior Specify a default action usage status for this control. When changed Use this to create a visual script that is run when this control has been changed. Variable Indicate whether you want to specify a calculation or select a Business Object variable. Calculation Specify a calculation to retrieve the parameter value. Business Object Item Select a Business Object variable as the Parameter value. Client extensions The field is included only for backwards compatibility. On field entry Do this when the control acquires system focus. On field exit Use this to create a script 164 MBPM Designer User's Guide Chapter 20 Designing a Form Property Name Description that is run when the user exits the field. Field has dependants of its own Check this to indicate that other field(s) on this form is dependent on this field, and it should therefore be updated when any field marked 'field is dependent on another' is changed. Field is dependent on another Check this if you want this field to be updated when any field marked 'field has dependents of its own' has been changed. Hint Type in the text you want to use to explain to a user how to use this control. Hint text appears when the use rolls or hovers over the control. Notes Use this to enter any specific notes for anyone using this control within the Designer environment. Status Property Name Description Name Specify a unique name to identify this control. This name is not visible at runtime. Position from top The position (in pixels) of this control, from the top edge of the form. Position from left The position (in pixels) of this control, from the left hand side of the form. MBPM Designer User's Guide 165 Chapter 20 Designing a Form Property Name Description Anchor Use this to adjust form control behavior on form resizing. There are four available options: Top, Bottom, Left and Right. Form controls will change position and be resized depending on the combination of options selected. Variable Indicate whether you want to specify a calculation or select a Business Object variable. Calculation Specify a calculation to retrieve the parameter value. Safety threshold Use this field to specify the value of the safety threshold for this status field. Danger threshold Use this field to specify the value of the danger threshold for this status field. Value as percentages Use percentages for threshold values. 100% Enter a value that represents "100%" for this status. (For example if you have 1,300 staff, enter '1, 300' in this field.) Display value Allows both the icon and value to be displayed. Alignment value Set the alignment of value to the left, right, top, or bottom for Status fields. Set the alignment of value 166 MBPM Designer User's Guide Chapter 20 Designing a Form Property Name Description to the left or right for Status Fields in Grids and Custom Lists. Business Object Item Select a Business Object variable as the Parameter value. Visibility depends on Indicates rules for showing the control. Warning Choose an image to display if this status state becomes a warning. Warning hint When deployed, the text entered is displayed as an alternative text when you hover your mouse over the field. Safety Choose an image to display if this status sate becomes a safety. Safety hint When deployed, the text entered is displayed as an alternative text when you hover your mouse over the field. Danger Choose an image to display if this status state becomes a danger. Danger hint When deployed, the text entered is displayed as an alternative text when you hover your mouse over the field. Drill down to Choose whether this status field drills down to one of the following: 1. No drill down No drill down is MBPM Designer User's Guide 167 Chapter 20 Designing a Form Property Name Description performed. 2. Initiate a Process Selecting this option displays the Dynamic, Process, Action, and Parameters fields. If you do not select Dynamic, you can select the static values for the Process and Actions available in the selected process from the respective drop-down lists. If you select Dynamic, you can click on the Expression Builder icon in the Process and Action fields to set the respective values. The Parameters field is displayed when static values are set for the Process and Action fields. The Parameters value can be set by clicking on the ellipsis button. The Expression Builder with Assignments Builder is launched where you can set the values to the form fields. 2. Administration form Selecting this option displays the Dynamic, Administration Form Group, Administration Form, and Parameters fields. If you do not select Dynamic, you can select the static values for the Administration Form Group and Administration Form 168 MBPM Designer User's Guide Chapter 20 Designing a Form Property Name Description from the respective dropdown lists. If you select Dynamic, you can click on the Expression Builder icon in the Administration Form Group and Administration Form fields to set the respective values. The Parameters field is displayed when static values are set for the Administration Form Group and Administration Form fields. The Parameters value can be set by clicking on the ellipsis button. The Expression Builder with Assignments Builder is launched where you can set the values to the form fields. 4. URL Enter a URL to open when this status button is clicked on. 5. Existing Folder Selecting this option displays the Folder ID field. This allows for an expressionable folder id to be specified. It accepts a Text return type. It is then possible to navigate to the specified folder during execution. Field is dependent on another Check this if you want this field to be updated when any field marked 'field has dependents of its own' has been changed. On field entry Use this to create a script MBPM Designer User's Guide 169 Chapter 20 Designing a Form Property Name Description that is run when the user enters the field. On field exit Use this to create a script that is run when the user exits the field. Client extensions The field is included only for backwards compatibility. Notes Use this to enter any specific notes for anyone using this control within the Designer. Note: In order to ensure the Status field refreshes correctly in the Web Client, the Status field tab order should be prior to the tab order of the field it is dependent on. Text Property Name Description Caption Choose a caption for this control. Normally it is the caption that is visible at run-time. Name Specify a unique name to identify this control. This name is not visible at runtime. Caption alignment Choose the position for the caption of this field above, below, to the left or to the right. Position from top The position (in pixels) of this control, from the top edge of the form. Position from left The position (in pixels) of this control, from the left hand side of the form. Anchor Use this to adjust form 170 MBPM Designer User's Guide Chapter 20 Designing a Form Property Name Description control behavior on form resizing. There are four available options: Top, Bottom, Left and Right. Form controls will change position and be resized depending on the combination of options selected. Field Alignment Choose the alignment (left, center, right) for the caption the user will see for this control. Width Specify the width, in pixels, of this control. Maximum length Indicate the maximum length (in number of characters) for this field. Mask Choose a validation mask for this entry: the user will not be able to enter data that does not 'fit' the mask you choose. The Mask property defines the format of the text to be entered at runtime. Value in a masked text field, entered at runtime, will be validated after entering data and exiting a field. Selecting a Mask To choose a predefined mask, for example, time of day, do the following: 1. Click on the ellipsis button that appears to the right of the Mask property. The Mask Picker dialog is displayed. MBPM Designer User's Guide 171 Chapter 20 Designing a Form Property Name Description 2. Select a mask from the list or enter your own in encoded format into the Mask field. The Mask formats are encoded and are referred to as Regular Expressions. For users who want to develop their own Regular Expressions for text masks, refer to http://www.regularexpressions.info/ If there are no suitable formats in the Mask Name list, click Browse to locate a folder with a suitable mask collection (file type of *.xml) file. Note: The Mask property is not available if the Password field is checked. Mask applies to Field The mask applies to field offers the following options: l Anywhere in the text l The start of the text l The end of the text l The entire text Choosing one of these options will cause the Mask field to change appropriately. Validation Clicking the Validate button causes the text in Test value property to be validated against the mask property. 172 MBPM Designer User's Guide Chapter 20 Designing a Form Property Name Description Password Indicates that this field is a password: if you choose this, data entered into the field will be masked. If you check the Password check box, MBPM is instructed to display all user input as asterisks and to store all user input in the database in encrypted form. A password text property will never be filled by the server: information travels only from the client back to the server, never the other way. Visibility depends on Indicates rules for showing the control. Default action behavior Specify a default action usage status for this control. Variable Indicate whether you want to specify a calculation or select a Business Object variable. Calculation Specify a calculation to retrieve the parameter value. Business Object Item Select a Business Object variable as the Parameter value. Client extensions The field is included only for backwards compatibility. When changed Use this to create a visual script that is run when this control has been changed. On field entry Do this when the control acquires system focus. MBPM Designer User's Guide 173 Chapter 20 Designing a Form Property Name Description On field exit Use this to create a script that is run when the user exits the field. Field is dependent on another Check this if you want this field to be updated when any field marked 'field has dependents of its own' has been changed. Field has dependants of its own Check this to indicate that other field(s) on this form is dependent on this field, and it should therefore be updated when any field marked 'field is dependent on another' is changed. Hint Type in the text you want to use to explain to a user how to use this control. Hint text appears when the use rolls or hovers over the control. Notes Use this to enter any specific notes for anyone using this control within the Designer environment. Using a text field to add a hyperlink There are two ways in which you can add a hyperlink to a form using a text field: 1. Using a Business Object: 1. Create a text box on a form. 2. Right-click on text box and click Add Variable. 3. In the Create a new Custom Variable window, enter a Variable Name, select a Business Object, and click OK. 174 MBPM Designer User's Guide Chapter 20 Designing a Form Depending on the selected Business Object type, a Form or Process Variable is created. 4. Using the Properties pane, set the following properties for the text box: Client Extensions: URL Variable: Business Object Calculation: "http://www." + AppBO.Company + ".com" Caption: Company Website URL The link that is displayed on the form will display the text entered in Caption property. 5. Click on the Form containing the text box to select it. 6. Using the Properties pane, set the following properties for the form: When user loads form: Click ‘Activate Visual Script Event-Handler’ A Visual Script Editor tab opens. 7. Drag and drop Assign Value(s) activity into the main pane of the Visual Script Editor. 8. Using the Properties pane, set the following properties for the AssignmentActivity1: Assignments: Click on the ellipsis to open the Assignments Builder. MBPM Designer User's Guide 175 Chapter 20 Designing a Form 9. In the Variable drop-down, select the variable that you have created. 10. In the value field, enter "opentext". 11. Click OK. 12. Save and deploy the process. The text box is displayed as a hyperlink. Note: Field is dependent on another property does not have an effect if the text field is used as a URL. 2. Using a calculated value: 1. Create a text box on a form. 2. Using the Properties pane, set the following properties for the text box: Client Extensions: URL Variable: Calculated Calculation: "http://www." + AppBO.Company + ".com" Caption: Company Website URL where: AppBO is a Business Object associated with the Process Company is a Process Variable associated with AppBO. The link that is displayed on the form will display the text entered in Caption property. 3. Save and deploy the process. The text box is displayed as a hyperlink. Note: Field is dependent on another property does not have an effect if the text field is used as a URL. For more information on using Business Objects and Visual Scripts, refer to Introduction to Business Objects and Introduction to Visual Scripts sections. 176 MBPM Designer User's Guide Chapter 21 Introduction to Form Segments Chapter 21 Introduction to Form Segments Form segments are re-usable collections of form controls. You can add controls to a form segment in the same way as you would when building a form; you can then reuse the form segment on other forms. Examples where form segments may be used are: l As header blocks for forms. l As blocks of controls that are used repeatedly such as name and address. MBPM Designer User's Guide 177 Chapter 21 Introduction to Form Segments In the above example, the same form segment with fields Issue date and Current date are used in Form 1 and Form 2 as footer. Form segments cannot be nested, that is, they cannot contain other form segments. When placing a form segment on a form, the form controls will display on the form offset from the top left corner of where the form segment was placed, by the same exact offset from the top left corner of where they are on the form segment. For example, if a text control is located at position (5, 5) on a form segment, and that form segment is placed on a form so that its top left corner is positioned at (10, 20) on the form, the text control from the form segment will display at position (15, 25) on the form. Creating and Using Form Segments To create a new form segment: 1. In the Home ribbon tab, Components group, click the Form Segment button. Whenever you create a new form segment, a blank form segment is displayed in a tabbed window in the main pane of the Designer. You can drag the corners or sides of this form to re-size it. 2. Edit the form segment's properties. Adding Controls to a Form Segment Form controls can be added to the form segment in the same way as for forms: In the form Toolbox, click on the required control and then click on the on the form segment where you want to place it. Designer displays the control and its corresponding properties. Note: To add several copies of a particular form control, hold down the Shift key while clicking on the desired control button, then click at each location on the form segment where you want the control placed. Click on the Pointer arrow or select another form control to disable the multiple placement function. Note: Due to changes in Form Segment behavior in 9.1, editable fields in Form Segments will behave differently when layered. If Form Segments with editable fields are placed on top of one another on a Form, then only the top Form Segment’s fields will be editable. This change will affect Forms developed prior to 9.1 that use this design. To counter this change it is now possible to set visibility at the Form Segment level which will allow exposure of editable Form Segment controls when placed underneath another Form Segment. Adding an instance of Form Segment to a Form To add an instance of form segment to a form: 178 MBPM Designer User's Guide Chapter 21 Introduction to Form Segments 1. Select the form in the main pane of the Designer. 2. In the Toolbox, Form Segments pane, click on the form segment you wish to add. 3. Click on the form where you wish to place the form segment. The contents of the form segment are added to the form. Once you have added a form segment, you can move it around the form and align it with other form controls in the usual way. Within a form, a form segment behaves like a single form control. You cannot select individual controls in the form segment. If you wish to edit controls in the form segment, edit them in the original form segment, not in a form to which the segment has been added. Any changes that you make to a form segment will automatically be reflected in any form that includes the form segment. You cannot place a form segment inside another form segment. Troubleshooting Consider a Project containing a Form with a Form Segment. If the instances of the Form Segment are resized, re-opening these Projects in a newer version may cause the Form Segment instance size to be reset to Form Segment size. You can correct the issue in the following ways: l l Open the Solution with the incorrect Form in the Designer. Open the Form. The size of the Form Segment instance will be reset. Resize Form Segment instance to desired size either by dragging the Form Segment instance edges or by editing its size from the Properties pane. Save the solution. The alternative way is to edit the appropriate Form file in a text editor before opening it in the Designer. This way the Form Segment instance size is kept unchanged. To do so, you should follow these steps: a. Open the Form file in a text editor. b. Find the XML section describing Form Segment instance. Normally, you can find it by a string FormSegmentReferenceEntity. The line will look like: <x:Object x:Name="Segment1" x:Type="{pref_ 1900572819:FormSegmentReferenceEntity}"> c. Add an entity version information x:Version="2.0.0.0" into starting XML tag. The resulting string should look like: <x:Object x:Name="Segment1" x:Type="{pref_ 1900572819:FormSegmentReferenceEntity}" x:Version="2.0.0.0"> d. Save and close the file. MBPM Designer User's Guide 179 180 MBPM Designer User's Guide Chapter 22 Introduction to Administration Forms Chapter 22 Introduction to Administration Forms Administration forms allow the user to carry out administrative processes. Note that Administration forms do not start a process. Creating Administration Forms To create a new administration form: 1. On the Home ribbon tab, Components group, click the Admin Form button. A blank administration form is displayed in a tabbed window in the Designer. You can drag the corners or sides of this form to re-size it. 2. Edit the form properties. 3. Drag and drop the controls in the toolbox to build the form. MBPM Designer User's Guide 181 182 MBPM Designer User's Guide Chapter 23 Admin Form Group Chapter 23 Admin Form Group Admin Form Group is a component that allows you to create a grouping of your administration forms. To create an Admin Form Group: 1. In the Home tab, Components group, click Admin Form Group. An Administration Form Group is displayed in the Inventory. Also, a tab is displayed in the main pane to set the name, caption, and a default group for your new Admin form group. If you select the default group, then all the new administration forms that you create will be added to this group. You can use the Grid tools tab to insert, delete, move or delete Admin form groups. Moving Admin Forms among Admin Form Groups In the Inventory, you can drag and drop administration forms between the admin form groups. Deleting Admin Form Groups In the Inventory, you cannot delete an administration form group without deleting the administration forms that it holds. MBPM Designer User's Guide 183 184 MBPM Designer User's Guide Chapter 24 Introduction to Roles Chapter 24 Introduction to Roles Roles are a way of grouping process users. Individuals may be grouped by function, by geographical location, by skill set, or by any other criteria relevant to your organization. Process users are defined as anyone within an organization who will be using the MBPM system. In most cases, this will include everyone on the staff roster, and may be expanded to include contract or temporary workers, suppliers, customers, and so on. Defining a Role When designing a process, Roles are used to decide whether: l Specific folders should appear on a user’s To Do list, Watch list or neither. l A user is permitted to undertake a particular action. l A user is permitted to view a form in a folder. l A specific form will appear on a users Blank Forms list. For example, “Credit Manager,” “Shipping Clerk,” and “Operations Controller” are all Roles which may have responsibility for particular stages and actions in the process. Using Roles rather than assigning particular individuals to the task makes it much easier to maintain a process. As individuals join and leave the organization or change duties within the organization, the administrator only has to reassign the Role to another user rather than ask the process Designer to change the process. Roles are defined through the Roles list, which may be accessed by clicking on the Roles button on the Home tab > Components group. Creating a Role To add a Role to the Roles list, first open the project who’s Roles you wish to modify. Roles can be classified as Group Roles and Dynamic Roles. Roles that do not have a formula are classified as Group Roles. Entering data into a formula field is the criterion which changes a role from being a Group Role to being a Dynamic Role. To create a new Role, on the Home ribbon tab, Components group, click on the Role button. The Roles List is displayed with a new row. MBPM Designer User's Guide 185 Chapter 24 Introduction to Roles Note: The default Roles created by Designer have Project as their scope. This means that the Role is available to all processes in the project. You can choose to limit the scope of a Role only to a Process by selecting Process from the Scope drop-down menu. 1. Click on the blank row to add a new row. 2. In the new row's Name field, enter the Role name. A Role name cannot be longer than 31 characters, and may only include letters (A-Z or a-z), numbers (0-9) and underscores. 3. In the Caption field, enter a caption for the Role. The Roles are referred by their caption. 4. In the Scope field, select the scope (project or library) from the drop-down menu. 5. In the Description field, enter a brief description of the Role. To dynamically define the users who may use a Role, follow steps 6 and 7 below. 6. In the Formula field, click on the button to display the Expression Builder. 7. Create the formula in the Expression Builder and click OK to return to the Roles List. The new Role is added to the list. Group Role A Group Role is a Role to which users are assigned, for example, “Area Managers.” The same user holds the Role for every MBPM process. A Group Role defined through the Roles dialog is added to the database when the process containing it is deployed. As new Group Roles are added to the database, their User/Role assignments become available to processes. In order to use a Group Role assignment, the Role must be manually added to the process where you wish to use it. Note: It is a good idea to make a master list of the Group Roles in your organization, and post it where you can refer to it whenever you are designing or modifying a process. This list will help prevent you from using different naming conventions for the same Role in different processes, which could result in a number of redundant Roles. (That is : The names “Marketing Director,” “Mktg. Director,” “Marketing Dir,” and “Mktg Dir” all refer to the same Role, but each would have to be assigned separately). Dynamic Role Dynamic roles may be based on formulas, database queries, content cached from directories, and so on. The following dynamic roles are set up automatically by Designer: l l "Everybody" is used to specify all users registered in the MBPM database "Metastorm Administrator" is used by the individual(s) with authority to administer the MBPM system, and should always be assigned to at least one registered user. This role may also be used by the process designer when creating and testing a process. 186 MBPM Designer User's Guide Chapter 24 Introduction to Roles l l "Originator" identifies the user who created a folder "Access" identifies all users who hold the role identified in each process' Limit access to property l "Metastorm Guest" is used to allow access by anonymous users l "To Do list" is used to indicate all users on whose To Do lists a folder currently resides l "Watch list" is used to indicate all users on whose Watch lists a folder currently resides l Dynamic roles are specific to a process. MBPM Designer User's Guide 187 188 MBPM Designer User's Guide Chapter 25 Introduction to Find and Replace Chapter 25 Introduction to Find and Replace “Find and Replace” searches all parts of a solution for the text that you type in. You can use Find and Replace to search for processes, events, forms, reports, roles, solution tables, variables, and text. You can extend your search by using wild cards to find words or phrases that contain specific letters or combinations of letters in MBPM components. Find Text You can quickly search for every occurrence of a specific word or phrase. 1. On the Home tab, in the Find and Replace group, click in the drop-down field. 2. Type the text that you want to search for. 3. Click on the Find button. The results are displayed in the Find Results pane. Advanced Find and Replace If you want to search for a specific word or phrase only in one or more MBPM components, you can use the Advanced Find/replace. 1. On the Home tab, in the Find and Replace group, click Advanced Find/Replace. The Advanced Find pane is displayed. 2. In the Find what field, type the text that you want to search for. 3. In the Look in field, select whether you want to search in the existing solution or all the open files. 4. In the Types included field, select the MBPM components in which you want to search for the text. 5. If you wish to also search in the library, select the Search in referenced libraries check box. 6. In the Find Options pane, you can filter your search by: n Match case n Find whole words only n Use Wildcards MBPM Designer User's Guide 189 Chapter 25 Introduction to Find and Replace 7. Click on the Find button to initiate the search. The results are displayed in the Find Results pane. Note: If you wish to find a specific object, for example form or process elements and so on, search for the object's caption. You can then click on the find result to go to the object. Find Results The Find Results pane displays the search results. Replace Text To replace text: 1. Click on a row to select it. Use shift + click or Ctrl + click to select multiple rows. You can also use the Select All button to select all the rows. 2. In the For selected items, replace "Browser" with field, type the replacement text. 3. Click on the Replace button. The text is replaced in the properties of the selected objects. Filtering the Results The standard filter functions are available for each column of the Find results pane. 1. Click on the right side of the column heading to display the filter icon. 2. Click on the filter button to display a selection menu. 3. In the menu, select the parameter to filter on. 190 MBPM Designer User's Guide Chapter 26 Introduction to Business Objects Chapter 26 Introduction to Business Objects A Business Object enables process designers to access and manipulate data in a business process. It provides a unified data access layer and can access various databases. Types of Business Objects Business Object Type Designer Business Objects Designer Business Objects are used to hold system, custom, and temporary variables. Designer Business Objects are used to store and share data between the different components of the Designer. Custom Business Objects MBPM Designer User's Guide Description Process Context Business Objects Holds the system variables and folder data. Process Business Objects Every process contains it own Process Business Object that cannot be deleted. It is used to associate the process with forms and reports. Process Business Objects are also used to store custom variables that can be used across components. Local Business Objects Local Business Objects are used to store the custom variables created on the form or report. Custom Business Objects can be created by the user to make connections to external source such as databases. Table Business Objects Connect to a single table in a database. Query Business Objects Connect to multiple views 191 Chapter 26 Introduction to Business Objects Business Object Type Description or tables in a database. LDAP Query Business Objects Connects to LDAP directories. Scripted Business Objects Connect to any data source. DMS Business Objects Connect to a Document Management System. Note: Business Objects have the functionality for read-only and read-write, but not writeonly. In the following example the project contains three Designer Business Objects: l Business Object 1 is used by process 1. l Business Object 2 is used by both processes 1 and 2. l Business Object 3 is used by process 2. It also contains Custom Business Object: l Business Object 11 and Business Object 22 connects to an external database. The toolbox provides access to all Business Objects available for the Project, allowing the user to drag a Business Object to the component area in order to associate the Business Object with the component (Process, Form, Report, and so on). 192 MBPM Designer User's Guide Chapter 26 Introduction to Business Objects Custom Business Objects Custom Business Objects can be created by the user to make a connection to an external source. Data Access The Data Access displays the Process Context Business Objects and any Business Objects that are associated with the component that is currently active in the main pane of the Designer. When a new process is created, the Data Access displays the System variables and the process Business Objects. When a form is created, the Data Access displays the System variables and the form's temporary Business Objects. The Data Access displays all the Business Objects that are bound to the selected component. In the Data Access you can do the following: l Bind Business Objects variables to form controls l View the Business Objects and Business Object variables bound to the form controls l Edit Process Business Objects parameters Note: References to Business Objects used within the Expression Builder are not updated after Business Object instance is renamed from the Data Access. In the Data Access, you can right-click on a Business Object and click on the Always Refresh option. Note: The Always Refresh option is available only to Read-Only Business Objects and not Read Write Business Objects. When you select this option for a Business Object, during run-time the fields that are bound to this Business Object will retrieve data from the data source each time an operation is performed on the field. Process Context Business Objects Process context Business Object holds the system variables. These Business Objects enable variables to be shared between processes. Each project contains an instance of the Process Context Business Object. The Process Context Business Object contains the system variables and cannot be changed by the user. It is always available on every component in the project. The Process Context Business Objects does not appear in the Toolbox, but is always displayed in the Data Access. Users cannot add or remove variables to or from a system Business Object. You cannot change the Process Context Business Objects properties. The following table lists the system variables and their return types. MBPM Designer User's Guide 193 Chapter 26 Introduction to Business Objects Variable Name Return type Description ActionCaption Text Returns the caption of the current action. A value will only be available if an action has been invoked. ActionName Text Returns the name of the current action. A value will only be available if an action has been invoked. ActionNote Memo Assigns a new note or gets the note associated with current action. ActionStartsStageCaption Text Returns the caption of the stage which the action flows into and therefore initiates. A value will only be available if an action has been invoked. ActionStartsStageName Text Returns the name of the stage which the action flows into and therefore initiates. A value will only be available if an action has been invoked. ClientType For use primarily in conjunction with the “Only show action if” and “Only show form if” properties to restrict the action/form to certain device types. The ClientType variable is populated with a value provided by the client with each Engine operation request. When a system action is being performed, the value will be blank. For example, it is now possible to use one of the following based on type of the client: ProcessContext.ClientType == “Web” ProcessContext.ClientType == “Mobile” Return type CurrentTime 194 Date/time Returns the date and time provided MBPM Designer User's Guide Chapter 26 Introduction to Business Objects Variable Name Return type Description by the database on which the MBPM Process Engine is running. FolderActionCount Integer Returns the number of actions (including creation actions) that have been performed on this folder. FolderCategory Text Returns the text value stored in the predefined folder variable called category. FolderDeadline Date/time Returns the deadline set for this folder. FolderID Text Returns the internal identifier for this folder. FolderName Text Returns the folder name shown on Watch and To Do lists for this folder. FolderOriginator Text Returns the login ID of the user (if any) who originally created this folder. FolderParent Text Returns the folder ID of the parent folder (if any). FolderPriority Integer Returns the priority (0 to 9) set for this folder. FolderSubject Text Returns the subject defined for this folder. FormCaption Text Returns the name of the caption of the form being used. FormCaption is a read only variable and is available in actions and stages. When used in an action, it displays the caption of the form or a blank string when there is no form available on the action. When used in a stage, it displays the caption of the active form tab. FormCaption can also be accessed from the Expression Builder and MBPM Designer User's Guide 195 Chapter 26 Introduction to Business Objects Variable Name Return type Description via Intellisense for Expressions and Server Side scripts. FormName Text Returns the name of the form being used. If no form is being used then no value is returned. ProcessCaption Text Returns the caption of the process to which this folder belongs. ProcessName Text Returns the name of the process to which this folder belongs. ProjectName Text Returns the name of the current project. ProjectVersion Text Returns the version of the current project. StageCaption Text Returns the caption of the current stage. StageName Text Returns the name of the stage which this folder is at currently. UserError N/A Displays an error message using its value. Note: MBPM User Error messages are not displayed correctly and cause an exception on IIS7 systems. In order to correct the above behavior it is necessary to either comment out or delete the following line from the Web Client web.config file: <httpErrors> <error statusCode="404" subStatusCode="13" path="ErrorPage.aspx" responseMode="Redirect"></error> </httpErrors> UserForm 196 Text Returns the form name if and only if the user has an action open. MBPM Designer User's Guide Chapter 26 Introduction to Business Objects Variable Name Return type Description UserInput List of text items Returns the text entered by the user into the current field. (If the form field contains a collection of data, return it as a list.) Note that UserInput variable can be accessed only from Expression Builder. (Expression Builder->Business Object->ProcessContext). UserLocale Text Returns the user's locale info for localization purposes. It contains the information necessary for performing locale specific operations such as formatting dates and times, numbers and comparing strings etc. UserName Text Returns the user name of the active user. WhenFolderCreated Date/time Returns the date and time that this folder was created. WhenFolderLastUpdated Date/time Returns the date and time that this folder was last updated either when it entered the stage or when it was processed by a loop back action. WhenStageStarted Date/time Returns the date and time that this folder entered the current stage. Cost and Revenue Enhancements This section provides details of the cost and revenue enhancements that have been added to the repository. The cost and revenue information can be used in a BPM process or for reporting purpose. New Columns in eEvent and eFolder Tables As part of the BPM database schema creation, the following new columns are created in the eEvent and eFolder tables. The new columns can be used to calculate values for cost and revenue purposes. New columns in eEvent table: l eIsException l eCost l eRevenue MBPM Designer User's Guide 197 Chapter 26 Introduction to Business Objects l eWorkTimeMinutes l eTotalCost l eTotalRevenue l eTotalWorkTimeMinutes New columns in eFolder table: l eIsException l eTotalCost l eTotalRevenue l eTotalWorkTimeMinutes The new schema columns are accessible via the ProcessContext Business Object variables. Cost and Revenue ProcessContext Business Object Variables The following table lists the Cost and Revenue ProcessContext Business Object variables: Variable Name Return type Description IsException Boolean It can be used to indicate when a folder is in an ‘exception’ state. The value is set to FALSE, by default. TotalCost Currency It allows you to add or edit a value that represents the total cost related to a folder at a specific stage in a process. This value can be used for reporting purposes. TotalRevenue Currency It allows you to add or edit a value that represents the total revenue gained while a folder is at a specific stage in a process. This value can be used for reporting purposes. TotalWorkTimeMinutes Number It allows you to add or edit a value that represents the total time spent by a folder at a specific stage in a process. This value can be used for reporting purposes. 198 MBPM Designer User's Guide Chapter 26 Introduction to Business Objects The above variables correspond to the new columns added to the eFolder and eEvent tables as displayed in the table below: ProcessContext Variable Corresponding eFolder Table Column Corresponding eEvent Table Column IsException eIsException eIsException TotalCost eTotalCost eTotalCost TotalRevenue eTotalRevenue eTotalRevenue TotalWorkTimeMinutes eTotalWorkTimeMinutes eTotalWorkTimeMinutes The above ProcessContext variables can be used to create event handlers that can add or edit values to the corresponding database columns. When adding data to the above columns in the eFolder table, a record is created in both the eFolder and eEvent table and the same columns are populated with the same values. The records have the same eFolderID. Note: An event handler can be created that will edit the existing values in the eFolder columns. If the columns are edited, the changes are reflected in the columns in the eFolder table. A new event record is created in the eEvent table with the new values and the difference between the initial values and the current values is recorded in the eEvent table columns eCost, eRevenue, and eWorkTimeMinutes respectively. Process Business Objects Process Business Objects are created when a process is created. Every process contains it own Process Business Objects that cannot be deleted and remains permanently associated to the process. You can add and remove custom variables to the Process Business Objects. Once variables have been added to the ProcessBusinessObject dataset, these variables will be accessible to any component (Process, Form, and Report) that binds to this ProcessBusinessObject. When you create a process, a process Business Object is created that can be viewed in the Business Objects Explorer. Note: When using an Assignment activity in a Visual Script, the eFolderId displayed in the Process Data Business Object of the variable tree is the Business Object parameter and not the system variable. Local Business Objects Local Business Objects are created when a form is created. A Local Business Object cannot be deleted and remains permanently associated to the component. Users can add variables to the Local Business Object. MBPM Designer User's Guide 199 Chapter 26 Introduction to Business Objects Local Business Objects do not connect to anything; they are just a store for custom variables created on the component. These variables will be temporary variables (these variables will be cached for the time that the form exists, but will be deleted afterward) and will not be accessible outside the form. Add a Variable to a Local Business Object 1. Click Manage Variables in the Home tab of the Designer toolbar. A window is displayed where you can add or delete variables for all the listed processes. 2. Select Business Object name and click Add Variable button. The new variable is added to the selected Business Object. You can change the data type of the variable by clicking in the Text field, which displays a list of choices. The default data type is Text. Delete a Variable from a Local Business Object 1. Click Manage Variables in the Home tab of the Designer toolbar. 2. Select the variable that you want to delete and click Delete Variable button. 3. Click Yes to confirm the deletion. Binding Processes to Forms and Reports When a process is created a corresponding process Business Object is also created. When a form or report is created, it is not visible to anything. To enable it to be seen by the business process, a form or report must be attached. Note: Reports do not support multiple Business Objects. To bind a process to a form: 1. Select the form in the Designer. The toolbox displays the Business Objects for all available processes. 2. In the toolbox, select the required process Business Object and drag it on to the form. The process Business Object appears in the Data Access. The form can now be seen by the process. Any variables added to the Process Business Object will be accessible to any component (form and report) that binds to the process Business Object. 3. Repeat step 2 for each process you wish to bind to the form. 200 MBPM Designer User's Guide Chapter 26 Introduction to Business Objects In the above example: 1. Select the form in the main pane of Designer, 2. Drag the Business Object that you want to bind to the form and drop it in the form. 3. The Business Object is now displayed in the Data Access. Note: When the process Business Object is added to the Data Access, an additional identifier is added to it. This identifier will be incremented each time the same Business Object is added. Example MBPM Designer User's Guide 201 Chapter 26 Introduction to Business Objects If process Business Object Process1 is added to a form, it will appear in the Data Access as Process11. If process Business Object Process1 is added to a form again, it will appear in the Data Access as Process12. Adding a Business Object to a Component Twice You can add the same process Business Object to the same form or report as often as you wish. A typical reason for doing this would be to enable a form to use different folderIDs (for example, parent folder or a child folder) at different stages. In the example below, Business Object "Process1BVTData1" is added to a form twice in the process. At stage 1 of the process, the form uses expression 1 to calculate the FolderID, but at stage 4 it calculates the ID using expression 2. Keep in mind the following: l l Server side paging is supported for one grid pointing to a particular Business Object. However, server side paging is not supported for multiple grids on the same form that point to the same Business Object. When you create a Business Object that points to a Solution Table and bind this Business Object to a form, any further edits to the Solution Table are not reflected in the Business Object. You must re-bind the Business Object to view these edits. Binding to Custom Variables Once a process Business Object has been attached to a form or report you can bind to any of the variables on the process Business Object. 202 MBPM Designer User's Guide Chapter 26 Introduction to Business Objects To bind a custom variable to a form or report: 1. Select the form or report in the Designer. 2. In the Toolbox, select the Process Business Object and drag-and-drop in to the component area. 3. In the Properties pane, in Variable field, select Business Object from the drop-down and then in Business Object Item field select appropriate Business Object variable from the drop-down list. This action places a control on the form/report. 4. Set the properties for the control. The length of custom variable name should be no longer than: 31 characters if you are using SQL Server 30 characters if you are using Oracle The same Business Object variable can be bound to different forms and reports or even repeated on the same component. The properties can be set independently for each instance. In the process, each element will receive the same data. Note: Spaces in table or column names associated with Business Objects is not supported when binding the Business Object to a report. No data is returned to the report when spaces are used. Binding to Process Context Variables The Process Context Business Object is always displayed in the Business Objects Explorer area of the process, form or report and can be used to bind to System variables. To bind a System variable to a process, form or report: 1. In the Toolbox, select the Business Object and drag-and-drop it in to the component area. 2. In the Properties pane, in Variable field, select Business Object from the drop-down and then in Business Object Item field select appropriate Business Object variable from the drop-down list. 3. Set the properties. Introduction to Custom Business Objects Custom Business Objects can be created by the user to make a connection to external sources such as databases. Custom Business Objects are stored within the project. They can also be added to the libraries. Database Custom Business Objects Database Custom Business Objects are used to map data in the database to the object on which the Business Object was created. There are two types of Database Business Objects: MBPM Designer User's Guide 203 Chapter 26 Introduction to Business Objects l Table l Query Depending on the type of Business Object, a relevant connection is displayed. A default "MetastormDefault" connection always exists in the Connection field. This connection can be configured from Designer Options. This connection cannot be removed. Table Business Object The Business Object connects to the database and retrieves the entire table specified in the Business Object data schema. The parameters determine which data from the table is utilized. Effectively, the Business Object maps data from the table to which ever object the Business Object was created on. A table Business Object can only select one table in the database. In the above example: l Business Object specifies the database location/connection. l The table is retrieved from the database to populate the data schema. l Represents the data schema. l Represents the data schema parameters. Note: If there is a schema column referenced to a variable within a form that has been edited or removed, a runtime error is displayed. In all cases if any columns within databases are either renamed, deleted, or added, you will need to click on Refresh button to refresh the Business Object affected to expose the updated schema and then redeploy the solution. Query Business Objects Query Business Objects can select data from multiple views or tables in the database. 204 MBPM Designer User's Guide Chapter 26 Introduction to Business Objects In the above example: 1. Business Object specifies the database location/connection. 2. The tables or views are retrieved from the database to populate the data schema. 3. Represents the data schema. 4. Represents the data schema parameters. Keep in mind these considerations: l Aliases should be provided for columns that do not have names in a Query Business Object, otherwise Grid with paging using this Business Object will not open in Web Client. For example: SELECT COUNT (ProductName) AS C, ProductID FROM Products GROUP BY ProductID l l Execute statement is not supported by the Query Business Object. A Query or Table Business Object created using a database (such as SQL Server) cannot be re-used in an environment using a different database (such as Oracle). A warning message is displayed, "Unable to connect to data source". This is because of differences in the syntax when creating a Connection using SQL Server and Oracle databases. This behavior is applicable in the Designer and Web Client components. The Business Object should be edited manually and all references to existing Business Objects need to be re-created. LDAP query An LDAP Query Business Object can connect to LDAP directories after you create a connection to an LDAP directory using Connection from the Components group. Scripted Custom Business Objects Allows process developers to create custom business objects via scripting that implement a customized interface using standard MBPM types. Data can be retrieved from any data source and may be consumed just as in the case of any other standard editable business object (i.e. Table). MBPM Designer User's Guide 205 Chapter 26 Introduction to Business Objects Document Management Support (DMS) Business Objects Provides the ability to connect to a content server. Note: SharePoint connections are not currently supported by this Business Object. Creating a Connection To establish a connection with a database, ODBC, LDAP, web service or Document Management System (DMS) use the Connection component. To create a new connection: l l On the Home ribbon tab, Components group, click on the Connection button. Select the Type of connection and select Database, ODBC, LDAP, Web services or Document Management System. If you select Database: From the Define Connection tab, select either SQL Server or Oracle, select or enter a server name, the logon information, and then select a database on the selected server. You can also click the Advanced radio button and click the Advanced button to display the Data Link Properties window from which you can establish a connection. Please note that only the following OLE DB Providers have been tested: l SQL Server Native Client 10.0 l SQL Native Client You will have the option to turn transaction support on or off so that they can work with MSDTC when the underlying database provider does not support MSDTC. To turn transaction support on, click Use DTC check box. If you select ODBC: Use system of user Data source name or a connection string to connect to the database. You will have the option to turn transaction support on or off so that they can work with MSDTC when the underlying database provider does not support MSDTC. To turn transaction support on, click Use DTC check box. Click Test Connection to test your connection. If connection succeeds, a 'Connection successful' message is displayed. Note: You will not be able to define ODBC connections in the Designer that uses 32-bit drivers if you are running Designer on a 64-bit operating system. The only work around, in this situation, is to use the Designer on a 32-bit operating system. If you select LDAP: Select the LDAP data source, authentication and logon information. The LDAP connection object allows you to define the details and credentials for a LDAP connection so that it may be reused in the Project (or Library) for accessing different attributes from the same LDAP location. 206 MBPM Designer User's Guide Chapter 26 Introduction to Business Objects Click Test Connection to ensure it is working and then select the Preview tab. Click the Refresh button and you should see the LDAP tree become available. You can drill down into it. In order to complete the creation of a connection so that it is available to be used elsewhere with a Project or Library you must save the changes you have made in creating the connection. If you select Web Service: You can browse to locate a web service or define your own web service connection. For more information, see Web Service Connection. For information on defining a connection for Document Management Systems, see Creating a Content Server DMS Connection. Web Service Connection To create a Web Service connection: 1. In the MBPM Designer, click the Home ribbon tab. 2. In the Components group of the Home ribbon tab, click Connection component. To connect to a Web Service using Web Service connection: 1. Click Locate Web Service in the lower pane. 2. Select the appropriate web service from your local computer, UDDI registry or any known URI address. If you choose "I know the URI" field, enter the URL for Web Service. For example: http://www.webservicex.net/globalweather.asmx?wsdl. Alternatively, you can browse to file on your local machine. 3. You can also choose from one of the following 3 serialization methods: Automatic (default) Data Contract XML Serialized In some cases the default automatic serialization method may not allow you to deploy the solution. When you try to deploy, you will notice an abrupt halt in the messages displayed in the Message pane indicating that the deployment was not successful. In such cases, selecting one of the other serialization methods will allow you to deploy successfully. Note: Code generation error is displayed if two web service connections are configured to use a web service on the same server via different protocols HTTP and HTTPS. Limitation of configuring connection to web service with 2-way SSL: To configure connection to web service, which is available via 2-way SSL transport, you should use WSDL file instead of Web Service URI. Also in this case, the "Test Connection" button will always return "Test unsuccessful". MBPM Designer User's Guide 207 Chapter 26 Introduction to Business Objects 4. In the MBPM Web Service Importer, click OK. The Endpoint name is automatically populated. 5. Enter a Caption for the Web Service. 6. If the Web Service is from a trusted source, select the option Trust Service Certificate. 7. If the Web Service needs authentication, select from: 8. Use Windows NT Integrated Security or 9. User name and Password. Note: When creating a Web Service connection to server using Windows NT Integrated Security, the Engine may not authenticate when executing the process. To correct this, click on Advanced tab and enter: clientCredentialType="Windows" to clientCredentialType="Ntlm". 10. To use a proxy for the Web Service: n Select the Use Proxy button. n Enter host, User name and Password. n You can select the option "Bypass the proxy server for local addresses" if you are using local address. 11. To test the connection: n Click Test Connection. n An attempt is made to access the endpoint URI mentioned in the WSDL file. n A "Connection successful" is returned for a valid connection. 12. In the Methods&Parameters tab, the available methods, return types and parameters are displayed. Set the values in the columns: Name: The method and parameter names are displayed in this column. Description: Provide a description here. The description provided here is displayed in the help area of the Expression Builder when you use the method or as displayed as a tooltip in the Visual Script Activities toolbox when you hover your mouse over the activity. Alias: By default, the method name is displayed in Expression Builder or Activity toolbox. To provide an alternative name, enter a name for the method to be displayed in Expression Builder or Visual Script toolbox. Category: You can promote the methods to a new category or choose from one of the available categories. The method is displayed in the chosen category in Expression Builder or Visual Script toolbox. You can also right-click on the Category column to sort the columns, choose the best fit, and customize the display. To customize the display, click Column Chooser and a pop-up window is displayed where you can drag and drop column names that you would like to hide. You can drag and drop from Column Chooser on to column names to display them again. 208 MBPM Designer User's Guide Chapter 26 Introduction to Business Objects Promote to Expression Builder and Visual Script toolbox: The method is exported to the chosen category in the Expression Builder or Visual Script toolbox based on selection. 13. Select the methods that you would like to promote to Expression Builder or Visual Script Toolbox. The Advanced tab can be used to edit the Web Service connection configuration settings. Note: Web Service connections built in the MBPM Designer 9.0 did not contain some of the properties required within the 9.0.1 release. To obtain these properties, the web service needs to be reactivated by clicking on the "Locate" button. Creating Custom Business Objects Create a new custom Business Object and select the connection type and connection. To create a custom Business Object: 1. On the Home ribbon tab, Components group, click on the Business Object button. The Business Object main pane tab is opened; you can add Business Object using the first row of the grid. The Business Object main pane displays all the custom Business Objects that exist within the project. You can edit existing Business Objects using in-place editing. 2. Click in the Name field and enter a name for the Business Object (optional). button and select the connection type from the drop3. In the Type field, click on the down list. The options are Table, Query, LDAP Query, Scripted and DMS. 4. If you already have defined connections, you can click in the Connection field, click on the button and select a predefined connection from the drop-down list. The parameters for a Business Object are independent from the Business Objects name, connection and type. You can change the connection of a Business Object without making any edits to the parameters. Server-side is enabled for database connections (tables and queries) only. The default server side page size can be set as a property of the Business Object. This property is enabled only when you check the property specifying that the Business Object is read-only since read-only and not-editable Business Objects will have the opportunity to support server side paging. If you select the “[None]” option, then "no server paging” will be the default when the Business Object instance is created. You can also type in a page size value that does not appear in the drop-down. The default server page size can be overwritten at the instance of the Business Object. To do this, use right-click for a Business Object instance in the Data Access. The default server page size can be modified in the Options dialog of the Designer. In v9, there will be no caching of server-side data on the client side. If you navigate to page 2 of the server page and then navigate back to page 1 of the server page, page 1 will need to be re-fetched. MBPM Designer User's Guide 209 Chapter 26 Introduction to Business Objects Editable grids will not implement server side paging for v9. If a user sorts a column, this will result in the sort occurring at the database level and then the results of the sort will be re-fetched for display in the web. The list of available types will depend on the user’s selection of the Business Object Connection type. For example, if the user has selected a connection for a database, then the list of available types will be Table and Query but will not include web service connections. The parameters pane is displayed after you choose a Table, Query, or LDAP query in Type field. 5. Define the Business Object's parameters. 6. Click > Save. Defining Custom Business Object Parameters You can define parameters for Custom Business Objects using the parameters tab of the Business Object. To define custom business object parameters: 1. Create a Business Object of type query. 2. Select the connection as MetastormDefault or create a new connection and select it. 3. The bottom pane displays Parameters, Query, Variable names, and Test tab. 4. Click on Query tab. 5. Click on Builder button. The Query Builder is launched. 6. In the Query Builder, drag and drop a table from the left pane in to the main pane of the Query Builder. 7. Select the rows that you want to be returned and set the desired criteria in the criteria column of the filter. 8. Click OK and the query is displayed in the Query pane. 9. Click on Test tab and click Refresh to display the results for the table and filtering that have been set. Using @ParameterName In the previous example, you can set the filtering criteria using @ParameterName. For example, in step 8 above, if the query is displayed as follows: SELECT RegionName FROM Regions WHERE Region = 'West' Instead of using 'West', you can use @RegionParam, and set the value of the parameter in the Parameters tab. For example, the query can be modified as follows: SELECT RegionName FROM Regions 210 MBPM Designer User's Guide Chapter 26 Introduction to Business Objects WHERE Region = @RegionParam l l l Click on the Parameters tab. You are prompted to add the parameter RegionParam to the Business Object. Click Yes. Choose a type, enter a description, and a Test value. You can use Expression Builder to select a test value. You can add more parameters in the Parameter tab and use them in your Query. Introduction to Database Business Objects You can create three types of database Business Objects: l Table Business Object l Query Business Object l LDAP Business Object Before creating any database Business Objects you should first set up any connections that you wish to use. A default "MetastormDefault" connection always exists in the Connection field. This connection can be configured from Designer Options. This connection cannot be removed. Note: Avoid using Date/Time column as a primary key. If you must use a Date/Time primary key, then disable time zone adjustment on the key column(s) in any editable grid that it is bound to. To create a Table, Query, or LDAP Query Business Object: 1. On the Home ribbon tab, Components group, click the Business Object button. A new Business Object is displayed in a tabbed window in the main pane of the Designer. 2. In the Type column, you can choose whether to create a Table Business Object, Query Business Object, or LDAP Query Business Object. Note: Editable Table Business Objects only support tables containing a primary key. After upgrading to SR3, solutions with LDAP Business Objects should either be redeployed or the "UseDTC=no;" parameter should be removed from the LDAP connection accessible from the MBPM Administrative Tools > Metastorm Repository > Projects > [Project Name] > Connections. Error message While using a table Business Object that contain fields with images in the database, the message request size may reach its maximum value during deployment. Consequently, an error message, "The maximum message size quota for incoming messages has been exceeded." may be displayed. To increase the message size quota, increase the maximum value in the following Windows Registry entry: HKEY_LOCAL_ MACHINE\SOFTWARE\Metastorm\e-work\Engine\WCF\MaxReceivedMessageSize Note: If you have created a Table Business Object, created parameters for the Business Object, and associated conditions for the parameters, it is important that when you want to MBPM Designer User's Guide 211 Chapter 26 Introduction to Business Objects delete the parameters of the Business Object, delete the conditions associated with the parameters too. Defining Table and Query Business Object Parameters The Table and Query Business Object parameters are used to select a table and rows to filter on. Table Business Object can be read/write and are able to update the table in the database. However it is possible to specify that a table Business Object is read-only. Query Business Objects are read-only. To define the Business Object parameters: 1. Select the Parameters tab. 2. Click in the first blank row of the grid. 3. In the Name field, enter a name for the parameter. 4. In the Type field, enter the parameter type. 5. In the Description field, enter a brief description of the parameter. 6. You can also enter a default value in the Default Parameter Value field. The default parameter value can accept either a constant value or you can display the Expression Builder to define an expression for the parameter value. 7. Select the Table tab. For a Query Business Object, a Query tab is displayed in place of Table tab. See Defining Custom Business Object Parameters for an example. 8. In the Table field click on and select the table to map to from the drop-down list. You will need to create a connection before the list of available tables is populated. Note: While you can select multiple parameters, you can only select one table. 212 MBPM Designer User's Guide Chapter 26 Introduction to Business Objects For a Query Business Object, a text box is available to type in your query. Alternatively, click on the Builder button on the bottom right corner to display the Query Builder. 9. To link user-defined parameters with the underlying data source, in the Filter field, click on the drop-down button to display the Filter dialog. 9. If the parameter is to be read-only, select the Read-only check box. If the check box is not checked, the parameter is allowed to update this row in the database table. 10. To add additional parameters, click in the blank row and repeat steps 4 to 11 above. 11. Click Test tab and click Refresh to display the rows that are returned. Auto Sequence In an editable Table Business Object, you can set a column's Behavior property to 'Auto Sequence' that allows the column's value to be automatically incremented when inserting rows. The ‘Auto Sequence’ is unavailable for a ‘Read-only’ Table Business Object and Query Business Object. The 'Auto Sequence' attribute is specifically for supporting Oracle databases. When the Business Object points to a MS SQL Server database, there is no effect of setting this attribute. The 'Auto Sequence' value can be set for a 'Primary Key' column; however, it will throw a Unique key validation error if you set an ‘Auto Sequence’ database column to be Unique from the database and then try to add multiple rows to the database. Note: The Auto Sequence option is available for Check type column of a Solution Table. This is because Check type variables are stored as smallint data type in the database. MBPM Designer User's Guide 213 Chapter 26 Introduction to Business Objects DMS Business Objects for Content Server Document Management System (DMS) integration allows BPM processes to route and manage documents (and document metadata) stored in the DMS. Business Objects provide a means to define connections to a Content Server repository and to determine the document attributes (metadata), which is accessible for use in the process. For more information, refer to Introduction to DMS Business Objects for Content Server. Introduction to Scripted Business Objects Scripted Business Objects allow Process Developers to write C# Server Scripts that implement Business Object interfaces. This allows the creation of Business Object types other than the existing Table, Query, and LDAP Query. After creating the Business Object type, you can define and use Scripted Business Objects in the same way as the standard types. This section is intended for users with a basic understanding of C# classes and interfaces. For more information about C#, see the MSDN C# Programming Guide. Developing a Scripted Business Object Server Script To create a scripted business object: 1. Create a new server-side script. 2. Create a new public abstract class. 3. Define a constructor for dynamic connections (optional). 4. Define variables as public properties using MBPM types. 5. Define supported parameters as public abstract properties using MBPM types (optional). 6. Implement all mandatory interfaces plus additional optional interfaces. a. IFieldAccess – provides generic programmatic access for a process designer to the Business Object. b. gerIDataSetAccess – is required for access to grids. c. grIPagedAccess – is required for access to Custom Lists and to support server-side paging. d. egISupportRefill – allows the Business Object to be loaded with different data using parameter values that change on each refill operation. e. geIIndexedAccess – is required to support Count and Indexed Access. f. IEditableAccess – allows the Business Object to save changes to its data source and is therefore required for supporting read/write actions (optional). Note: You can define Scripted Business Objects within external assemblies as well as Server-side scripts. 214 MBPM Designer User's Guide Chapter 26 Introduction to Business Objects The Anatomy of a Scripted Business Object A Scripted Business Object must implement a base class with a well-defined public programmatic interface. This interface is used internally by the Designer and Engine, and externally by Process Designers using programmatic access in Expressions, Visual Scripts, and custom code. This chapter describes the key elements of a Scripted Business Object. These elements are used within sample solutions supplied with the BPM install build and include: l Base Class l Constructor with Connections l Parameters (optional) l Variables l Interfaces MBPM Designer User's Guide 215 Chapter 26 Introduction to Business Objects Code snippets are used to provide an example of each element's implementation. The Scripted Business Object Base Class The implementation of the Scripted Business Object should include all necessary interfaces for the functionality to be supported. The class should be defined as abstract to indicate that this class is intended only to be a base class for use as a Business Object. /// <summary> /// This class implements a business object that retrieves data from a /// stored procedure in the Northwind database defined using connections. /// </summary> public abstract class CustomerOrderHistory : IDataSetAccess, ISupportRefill Constructor with Connections (optional) A Scripted Business Object can be designed to allow a process designer to dynamically pass in a connection to be used by the business object. When a constructor is included to accept a connection, a connection can be specified within the connection property of the Business Object Definition. Use this to abstract connection information from the type and to re-use the MBPM connection pool. Business Objects can utilize database connections (MetastormDefault, DB, and ODBC) or LDAP connections. For a database type connection, two constructors must be supplied. The first must have a single parameter of type MboConnectionInfo for database connections that have not previously been instantiated. The second must have a single parameter of type 216 MBPM Designer User's Guide Chapter 26 Introduction to Business Objects MboConnection for connections that have already been instantiated. For LDAP connections, the constructor should have a single parameter of type LDAPMboConnection. Note: Web Service connections cannot be passed in to a script due to differences in their interfaces. When a scripted business object is written to communicate with a particular web service, it normally involves re-writing the script. The code snippet below illustrates an example of an instantiation of an object which accepts a database connection parameter dynamically passed into the type. /// <remarks> /// This constructor may be called by the constructor of an inheriting /// business object script that takes a pre-instantiated connection to its data source. /// </remarks> public ScriptedBusinessObject(MboConnection connection) : this() { this.Connection = connection; } /// <remarks> /// This constructor may be called by the constructor of an inheriting /// business object script that takes the connection info for its data source. /// </remarks> MBPM Designer User's Guide 217 Chapter 26 Introduction to Business Objects public ScriptedBusinessObject(MboConnectionInfo connectionInfo) : this() { if (connectionInfo != null) { if (connectionInfo.MetastormDefault) this.Connection = new EngineMboConnection(); else this.Connection = new MboConnection(connectionInfo); } } Parameters (optional) You can design a Scripted Business Object to allow a process designer to dynamically pass in parameters. These are used to initialize the business object when the data is read. When including parameters in the definition of a Scripted Business Object, they are displayed within the Business Object Definition pane. This allows the process designer to add default values for the Business Object Definition. The parameters for a scripted business object are declared as public, abstract, read-only properties of an MBPM runtime type. These properties are overridden with the value(s) specified in the business object definition or business object instance. The following snippet is taken from a sample which implements an externally defined Business Object connection. public abstractMetastorm.Runtime.Types.Text CustomerID { get; } 218 MBPM Designer User's Guide Chapter 26 Introduction to Business Objects Variables The business object's variables are declared as public virtual properties of an MBPM runtime type. To use the business object with grids, the property names must match the names of the columns in the DataTable contained in the DataSet returned by the Read() method required by IDataSetAccess. Note: Data types in MBPM and .Net must be correctly mapped. Variables are not listed in the Expression Builder where the 'virtual' modifier is omitted. MBPM Designer User's Guide 219 Chapter 26 Introduction to Business Objects The following table lists the type mappings between MBPM and .NET types. MBPM Type .NET Type Sample casts/conversions Text string string = Text; Text = string; Integer int int = Integer; Integer = int; Real double double = (double) Real; Real = double; Memo string string = Memo; Memo = string; Currency decimal decimal = Currency; Currency = decimal; DateTime 220 System.DateTime System.DateTime = DateTime.ToDateTime ().DateTime; MBPM Designer User's Guide Chapter 26 Introduction to Business Objects MBPM Type .NET Type Sample casts/conversions DateTime = System.DateTime; Check bool bool = Check Check = bool Note: Neither variables nor parameters should be defined using the List data type. The following example is taken from a sample which implements an internally defined Business Object connection. public virtual Metastorm.Runtime.Types.Text Author { get { return GetField<string>("Author"); } set { SetField<string>("Author", value); } } public virtual Metastorm.Runtime.Types.Integer PublishYear { get { return GetField<int>("PublishYear"); } set { SetField<int>("PublishYear", value); } } public virtual Metastorm.Runtime.Types.Currency Price { get { return GetField<decimal>("Price"); } set { SetField<decimal>("Price", value); } } Interfaces There are a range of interfaces available for use within Scripted Business Objects to implement Business Object types. Each of these interfaces has been defined within Metastorm.Runtime.Contracts.Mbo. Detailed below are the main interfaces that are likely to be needed to implement the Business Object types to work successfully with the Designer and run-time features provided in BPM. IFieldAccess IFieldAccess provides generic programmatic access for a process designer to the Business Object. Failure to implement this interface will cause unexpected errors with generically written code against the Business Object. The properties of IFieldAccess are listed in the following table. MBPM Designer User's Guide 221 Chapter 26 Introduction to Business Objects Property Description Parameters Example GetField () fieldName public object GetField(string fieldName) Returns field value { if (fieldName == "ProcessNames") return this.ProcessNames; else return null; } GetFieldType() Returns field value fieldName public object GetField(string fieldName) { if (fieldName == "ProcessNames") return this.ProcessNames; else return null; } SetField () Sets new value to the field fieldName, newValue public void SetField(string fieldName, object newValue) { if (fieldName == "ProcessNames") data = (Metastorm.Runtime.Types.List) newValue; } IDataSetAccess IDataSetAccess is required for access to grids. Failure to implement this will cause errors during deployment when the business object is bound to either grids or custom lists. The properties of IDataSetAccess are listed in the following table. Property Description Example Read() Retrieves the data and returns a data set containing the data contained in the business object. public System.Data.DataSet Read() Write() This method is called to public void Write 222 MBPM Designer User's Guide Chapter 26 Introduction to Business Objects Property Description Example apply changes to the business object’s data set. (System.Data.DataSet dataSet) IPagedAccess IPagedAccess is required for access to Custom Lists and to support server-side paging. Where an attempt is made to sort a column that doesn’t implement IPagedAccess, an error is displayed. The properties of IPagedAccess are listed in the following table. Property Description Example TotalPageCount Returns the current total page count of the entire query (including any partial page). int TotalPageCount { get; } TotalRowCount Returns the current total row count of the entire query. int TotalRowCount { get; } CurrentPage Current page, default to -1 if the data has not yet been requested. int CurrentPage { get; } PageSize Returns the number of rows which make up one (full) page in Client. This is set in the business object instance using the Designer. int PageSize { get; } RequestPage Indicates the current page. The engine will set this value before a call to <see cref="IDataSetAccess.Read"/> is made. int RequestPage {} SortColumns Defines the requested sort order for the data. This needs to be applied to the method/logic that queries the data source. IList<KeyValuePair<string, SortDirection>> SortColumns { get; set; } Filter Defines the requested filter(s) for the data. This needs to be applied to the method/logic that queries the data source. Metastorm.Runtime.Contracts.Mbo.IBusinessObjectFilter Filter { MBPM Designer User's Guide 223 Chapter 26 Introduction to Business Objects Property Description Example get; set; } IEditableAccess IEditableAccess allows the Business Object to save changes to its data source and is therefore used for supporting read/write actions. The properties of IEditableAccess are listed in the following table. Property Description Example Commit() Commits any changes in the business object to its backing data store. public void Commit() { if (data.HasChanges()) { StringBuilder sb = new StringBuilder(); using (System.IO.StringWriter writer = new System.IO.StringWriter (sb)) data.WriteXml(writer); string dataString = Convert.ToBase64String (Encoding.UTF8.GetBytes (sb.ToString())); Mstm.DeleteAttachment (new ProcessContext ().FolderId, FileName); Mstm.SaveAttachment(new ProcessContext ().FolderId, FileName, dataString); } } ReadOnly() 224 Gets a value indicating whether the business object may be edited. This property is overridden with the value specified in public virtual bool ReadOnly { get { return false; } MBPM Designer User's Guide Chapter 26 Introduction to Business Objects Property Description Example the business object definition, and therefore it must be marked 'virtual'. } ISupportRefill ISupportRefill allows the Business Object to be loaded with different data using parameter values that change on each refill operation. The properties of ISupportRefill are listed in the following table. Property Description Example Commit() AlwaysRefresh Gets a value indicating whether the business object should retrieve its public virtual bool AlwaysRefresh { data on every request. get { return false; } The value of property is overridden by instances of the business object, } and therefore it must be marked 'virtual'. IIndexedAccess Use IIndexedAccess to support Count and Indexed Access. Failure to implement this interface can cause unexpected errors with generically written code against the Business Object. The properties of IIndexedAccess are listed in the following table. Property Description Example Count Provides a total count of records in the business object. public int Count { get { if (data != null && data.Tables.Count > 0) return data.Tables [0].Rows.Count; else return 0; MBPM Designer User's Guide 225 Chapter 26 Introduction to Business Objects Property Description Example } } CurrentIndex Provides the currently active record within the business object. public int CurrentIndex { get; set; } Business Object Implementation Types This chapter provides information on the sample Scripted Business Object solutions supplied with the BPM install build. The following implementation types are covered: l Read-Only Business Object l Editable Business Object l Externally Defined Connections Utilization l Internally Defined Connections Utilization Note: To successfully deploy the sample solutions, copy the .NET assembly System.Xml.Linq.dll into the following locations: C:\ProgramFiles\Metastorm\BPM\Designer\CustomLib C:\ProgramFiles\Metastorm\BPM\Engine\CustomLib Read Only Business Object This implementation type uses a sample solution that implements a read only business object. It retrieves news items from a Really Simple Syndication (RSS) feed. Interfaces The implementation combines the IDataSetAccess and IPagedAccess interfaces. l l Implementing the IDataSetAccess interface allows the business object to work with grids. Implementing the IPagedAccess provides the ability for the business object to support paging and can therefore be used in custom lists. IDataSetAccess #region IDataSetAccess Members This interface retrieves the data and returns a data set containing the data contained in the business object. The following steps complete these actions: l Retrieves the data. This returns a dataSet containing the data contained in the business object. public System.Data.DataSet Read() l Loads the news feed. XDocument feed = XDocument.Load(this.FeedUri); 226 MBPM Designer User's Guide Chapter 26 Introduction to Business Objects l Queries the data, grooming as we go. var newsItems = from i infeed.Descendants("item") select new object[] { i.Element("title").Value.Trim(), i.Element("description").Value.Trim(), i.Element("link").Value.Trim(), ...... l Defines the schema of the data set DataSet ds = new DataSet(); ds.DataSetName = "News"; DataTable tbl = ds.Tables.Add(); tbl.TableName = "News"; tbl.Columns.Add("Title", typeof(string)); tbl.Columns.Add("Description", typeof(string)); .... l Fills the data set foreach (object[] item in newsItems) tbl.Rows.Add(item); l Indicates that this is the initial state of the data ds.AcceptChanges(); this.data = ds; l Applies changes to the business object's data set. (RSS feeds are read only, therefore this method is left empty). public void Write(System.Data.DataSet dataSet) Parameters Declare the parameters for a scripted business object as public, abstract, read-only properties of an MBPM runtime type. These properties are overridden with the value(s) specified in the business object definition or business object instance. l Get the internet address of the feed, for example http://www.metastorm.com/rss/news.xml public abstractMetastorm.Runtime.Types.Text FeedUri { get; } Variables Declare the business object variables as public virtual properties of an MBPM runtime type. To use the business object with grids or custom lists, the property names must match the names of the columns in the data table. If the 'virtual' modifier is omitted, then the variables will fail to be listed in the Expression Builder. public virtual Metastorm.Runtime.Types.Text Title { MBPM Designer User's Guide 227 Chapter 26 Introduction to Business Objects get { return GetField<string>("Title"); } } public Metastorm.Runtime.Types.Text Description { get { return GetField<string>("Description"); } } .... Paging IPagedAccess Implementing the IPagedAccess interface allows the Business Object to provide paging support. It can therefore be used for Custom Lists. #region Custom List Support (IPagedAccess) l The following returns the current total page count of the entire query (including any partial page) public int TotalPageCount { get { return 1; } } Implementation The following steps complete the implementation of the Read Only Scripted Business Object: l Define the server script within the Business Object MetastormNewsFeed. l Bind the MetastormNewsFeed Business Object to a Custom list. The Custom List displays details of the MBPM News Feed from the internet address provided in Parameters above. Editable Business Object This implementation type uses a sample solution that implements an editable Business Object. The Business Object maintains a list of books stored in an XML data source. Interfaces The implementation combines the IDataSetAccess, IEditableAccess and IPagedAccess interfaces. l l l Implementing the IDataSetAccess interface allows the business object to work with grids. Implementing the IEditableAccess allows the Business Object to save changes to its data source. Implementing the IDisposableAccess interface allows instances of the class to be released from memory. IDataSetAccess #region IDataSetAccess Members The following steps describe the procedure for implementing an editable Business Object. l data holds the data for this business object. private DataSet data; 228 MBPM Designer User's Guide Chapter 26 Introduction to Business Objects l Initialize a new instance of the BookList class and set up caching events. Gets any previously loaded data from the cache. public BookList() { CacheHelper.LoadFromCache += LoadDataFromCache; CacheHelper.SaveToCache += SaveDataToCache; LoadDataFromCache(this, EventArgs.Empty); } l Retrieve the data. This returns a data set containing the data contained in the business object. public DataSet Read() l Define the schema of the data set. data = new DataSet(); data.DataSetName = "BookList"; .... l Retrieve the attachment. attachmentData = Mstm.ReadAttachment(new ProcessContext().FolderId, FileName); l Load the data from the attachment into the data set. using (StringReader reader = new StringReader(Encoding.UTF8.GetString (Convert.FromBase64String(attachmentData)))) data.ReadXml(reader); l Apply the changes to the business object's data set. public void Write(DataSet dataSet) { if(dataSet.HasChanges()) data.Merge(dataSet.GetChanges()); } IEditableAccess This interface gets a value that indicates whether the business object may be edited. #region IEditableAccess Members l Commits any changes to the business object's data store. using(System.IO.StringWriter writer = new System.IO.StringWriter(sb)) data.WriteXml(writer); MBPM Designer User's Guide 229 Chapter 26 Introduction to Business Objects string dataString = Convert.ToBase64String(Encoding.UTF8.GetBytes (sb.ToString())); Mstm.DeleteAttachment(newProcessContext().FolderId, FileName); Mstm.SaveAttachment(newProcessContext().FolderId, FileName, dataString); IDisposable #region IDisposable Members public void Dispose() { CacheHelper.LoadFromCache -= LoadDataFromCache; CacheHelper.SaveToCache -= SaveDataToCache; } Variables Declare the business object's variables as public virtual properties of an MBPM runtime type. To use the business object with grids, the property names must match the names of the columns in the data table. If the 'virtual' modifier is omitted, then the variables will fail to be listed in the Expression Builder. public virtual Metastorm.Runtime.Types.Text ISBN { get { return GetField<string>("ISBN"); } set { SetField<string>("ISBN", value); } } public virtual Metastorm.Runtime.Types.Text Title { get { return GetField<string>("Title"); } set { SetField<string>("Title", value); } .... Implementation The following steps complete the implementation of the Editable Scripted Business Object: l Define the server script within the Business Object BookListData. l Bind BookListData to a form BookListForm. The form displays details of the publications passed in from the XML source as described previously. Externally Defined Connections Utilization This implementation type uses a sample solution that implements an editable Business Object, which retrieves data from a database stored procedure. 230 MBPM Designer User's Guide Chapter 26 Introduction to Business Objects Interfaces This implementation combines the IDataSetAccess and ISupportRefill interfaces. Implement the IDataSetAccess interface to allow a Business Object to work with grids. Implementing the ISupportRefill interface to load the Business Object with different data using parameter values that change on each refill operation. IDataSetAccess #region IDataSetAccess Members This interface retrieves the data and returns a data set containing the data contained in the business object. public System.Data.DataSet Read() The following actions complete the implementation of the IDataSetAccess interface: l Prepare the parameters to the stored procedure. l Execute the stored procedure. l Indicate that this is the unmodified state of the data. l Apply changes to the business object's data set: public void Write(System.Data.DataSet dataSet) { // The stored procedure is read only, therefore this method is left empty } ISupportRefill #region ISupportRefill Members This interface gets a value indicating whether the business object should retrieve its data on every request. Class Definition public abstract class CustomerOrderHistory : IDataSetAccess, ISupportRefill l Holds the data for this business object. private DataSet data = null; l References the connection for this business object. private MboConnection connection = null; l Initializes a new instance of the CustomerOrderHistory class. The MboConnectionInfo parameter to this constructor indicates that the business object requires a database connection. public CustomerOrderHistory(MboConnectionInfo connectionInfo) { // Get access to the appropriate connection if (connectionInfo != null) MBPM Designer User's Guide 231 Chapter 26 Introduction to Business Objects { if(connectionInfo.MetastormDefault) connection = newEngineMboConnection(); else connection = new MboConnection(connectionInfo); } Parameters Declare the parameters for a scripted business object as public, abstract, read-only properties of an MBPM runtime type. These properties are overridden with the value(s) specified in the business object definition or business object instance. public abstractMetastorm.Runtime.Types.Text CustomerID { get; } Variables Declare the business object's variables as public virtual properties of an MBPM runtime type. To use the business object with grids, the property names must match the names of the columns in the data table. If the 'virtual' modifier is omitted, then the variables are not listed in the Expression Builder. public virtual Metastorm.Runtime.Types.Text ProductName { get { return GetField<string>("ProductName"); } } public virtual Metastorm.Runtime.Types.Integer Total { get { return GetField<int>("Total"); } } Implementation The following steps complete the implementation of the externally defined connections Business Object. l l Define the server script within the Business Object CustomerOrders. Bind the CustomerOrders Business Object to an Administration Form CustomerOrderHistoryLookUp. The Administration Form displays a Customer Order History within a grid. Internally Defined Connections Utilization This implementation type uses a sample solution that implements an editable business object that retrieves the names of deployed processes. This uses a web service connection MetadataSvc which has been internally defined within the Business Object Server Script. Class Definition public abstract class ProcessMetadata : IFieldAccess Interfaces This implementation uses the IFieldAccess interface. 232 MBPM Designer User's Guide Chapter 26 Introduction to Business Objects l Implementing the IFieldAccess interface allows the Business Object to work with fields and expressions. IFieldAccess #region IFieldAccess Members This returns field type by its name The following actions complete the implementation of the IFieldAccess interface: l Returns field value. l Sets new value to the field. Variables Declare the business object variables as public virtual properties of an MBPM runtime type. To use the business object with grids, the property names must match the names of the columns in the data table. If the 'virtual' modifier is omitted, then the variables are not listed in the Expression Builder. public virtual Metastorm.Runtime.Types.List ProcessNames { The following actions complete the implementation of the variables declared in the sample solution: l Create a connection using (MetadataSvc conn = new MetadataSvc()) l Get the Web Service channel MetadataServiceSoap service = conn.GetChannel("MetadataServiceSoap"); l Get the data DataSet results = service.AvailableProcessMaps(); data = results.Tables[0].GetFields<string>("eMapName").ToArray(); Implementation The following steps complete the implementation of the internally defined connections Business Object. l l Define the server script within the Business Object ProcessMetaDataObject. Bind the ProcessMetaDataObject Business Object to an Administration Form AvailableProcessMaps. The Administration Form displays a list of processes available for the specific installation of the Designer. Creating Scripted Business Objects To create a Custom Scripted Business Object in the main Business Objects pane, follow the steps defined in Creating Custom Business Objects. MBPM Designer User's Guide 233 Chapter 26 Introduction to Business Objects Defining Scripted Business Objects Parameters and Scripts You can define parameters for Scripted Business Objects using the parameters tab of the Business Object. Follow these steps to define a Scripted Business Object Script: 1. Create a Business Object of type Scripted in the main pane tab of the Business Objects Components group (refer to Creating Custom Business Objects to complete this step). The bottom pane displays Parameters and Script tabs. 2. Click on the Script tab. A dropdown list field Script Class Name appears. A Refresh button is also displayed beneath this. 3. Click the down arrow in the dropdown list field. A list of Script names available to the current project appears in the list. 4. To name the Scripted Business Object, select a value from the list of Script names. 5. Click the Refresh button to reconcile the Business Object definition against the latest version of the Server Script. This should be performed whenever there has been a change in the underlying Server Script. Implementing a Scripted Business Object for a Grid Control The following example describes how to implement a Scripted Business Object that uses a Grid control type. 1. Create a new scripted MBO (e.g. Script1) as described in step 1 above. 2. Click on the Script tab and select the script name from the Script class name dropdown list from Script sheet. 3. To make this MBO editable - unmark Read Only checkbox. 4. Open Form1 (it was created together with solution). 5. Add Script1 Scripted Business Object into the Form. 6. Select all rows(variables) from the previously mentioned MBO (Other Business Objects panel) and drag them onto the Form. 7. Add a Grid control type to the form . A Grid with selected columns will appear on the Form. 8. Select the required properties of the Grid (e.g. editable, add paging, multi-sorting etc). 9. Deploy the solution and open it in the Web Client. Troubleshooting A series of errors are displayed at runtime when attempting to open a report or blank form containing custom Business Objects that retrieve data from a database held on a separate database server. To prevent these errors, change the MSDTC configuration. 234 MBPM Designer User's Guide Chapter 26 Introduction to Business Objects MSDTC Configuration To connect a Table Business Object or Query Business Object executing from the MBPM Process Engine to a database running on a separate machine, the MSDTC configuration settings should be changed. The following configuration is required on both Engine and Database systems: 1. Go to Start>Control Panel> Administrative Tools. 2. Open Component Services>Computer>My Computer. 3. Right-click My Computer and click Properties. 4. Select the MSDTC tab and click the Security Configuration button. 5. Under Default Coordinator section, select Use Local Coordinator. 6. Select Network DTC Access. 7. Under Transaction Manager Communication, select Allow Inbound and Allow Outbound. 8. Click OK. When you click OK, you will be prompted for MSDTC service to restart. 9. Once the MSDTC service is restarted, restart the MBPM Process Engine Service by going to Start > control Panel > Administrative Tools > Services. The following article describes the steps to overcome error message that is displayed when you try to start a transaction in MSDTC: "New transaction cannot enlist in the specified transaction coordinator": http://support.microsoft.com/kb/922430 A summary of configuration change is displayed below from the article: 1. Click Start, click Run, type regedit, and then click OK. 2. Locate the following registry subkey: 3. HKEY_LOCAL_MACHINE\Software\Microsoft\MSDTC 4. Right-click MSDTC, point to New, and then click DWORD Value. 5. Type CmMaxNumberBindRetries, and then press ENTER. 6. Right-click CmMaxNumberBindRetries and then click Modify. 7. Click Decimal. 8. In the Value data box, type 60. This value increases the length of time that the client computer waits for the bind packet response from the server computer. This value is double the number of seconds before the client computer stops the transaction if the client computer does not receive the bind packet response. For example, a value of 60 equals 30 seconds. The value of 60 is only a recommended value. Additional testing on your configuration may be required. 9. Click OK. 10. Restart the computer. The DTCPing tool is designed to assist with troubleshooting Microsoft DTC firewall issues. You can download this tool from the Microsoft website. MBPM Designer User's Guide 235 Chapter 26 Introduction to Business Objects http://www.microsoft.com/DOWNLOADS/details.aspx?FamilyID=5e325025-4dcd-4658a549-1d549ac17644&displaylang=en For more information on troubleshooting MSDTC issues using DTCPing tool, follow the steps mentioned here: http://blogs.msdn.com/distributedservices/archive/2008/11/12/troubleshooting-msdtcissues-with-the-dtcping-tool.aspx 236 MBPM Designer User's Guide Chapter 27 Query Builder Chapter 27 Query Builder You can use the Query Builder to view a single query or sub-query. The Query Builder main window has the following areas: l l l l l The Query Building Area is the main area where the visual representation of the query will be displayed. This area allows you to define source database objects and derived tables, define links between them and configure properties of tables and links. The Columns Pane is located below the query building area. It is used to perform all necessary operations with query output columns and expressions. Here you can define field aliases, sorting and grouping, and define criteria. The Query Tree Pane is located at the left. Here you can browse your query and quickly locate any part of it. The page control above the query building area will allow you to switch between the main query and sub-queries. The small area in the corner of the query building area with the "Q" letter is the union sub-query handling control. Here you can add new union sub-queries and perform all necessary operations with them using popup menu. MBPM Designer User's Guide 237 Chapter 27 Query Builder Building a single query Active Query Builder allows you to build complex SQL queries visually. You can: l Build queries with different join types. l Build queries with sorting, grouping and complex criteria. l Build queries with different server-specific options. Adding objects to the query There are several ways to add database objects to the query: 1. Use the tree on the right that displays database objects. Double-click on objects or drag them to the query building area. To find the object you need, type the first letters of its name or scroll down the tree. The object within the tree can be grouped by Database, Schema or Type. To remove an object from the query, select it and press the Del key or click the Close button in the object header. 2. Right-click the query building area and select Add Object. The Add New Object window is displayed. You can add multiple objects in the Add New Object dialog box. The objects are grouped by type: Tables, Views, Procedures (Functions) and Synonyms. You can use the Ctrl key to select multiple objects and then click Add Object. 238 MBPM Designer User's Guide Chapter 27 Query Builder 3. After you finish adding objects, click Close. For database servers that have schemas or allow selection of objects from different databases, you can filter objects by database or schema name by selecting the necessary schema or database from the combo box at the top of the window. Setting object aliases To set an alias for an object or derived table in the query, right-click on the object and select the Properties item from context popup menu or double-click on the object header. The Datasource Properties dialog is displayed. The Datasource Properties dialog can contain other server-specific datasource options, but the Alias property is the same for all database servers. Joining tables Adding and removing joins When two objects referenced with a foreign key relationship are added to the query, they become joined automatically with INNER JOIN. For those servers that have no support of JOIN clause, Active Query Builder adds condition to WHERE part of the query. To create a link between two objects (that is, join them manually), you should select the field by which you want to link the object with another and drag it to the corresponding field of the other object. After you finish dragging, a line connecting the linked fields will appear. Key cardinality symbols are placed at the ends of link when corresponding relationship exists in the database. MBPM Designer User's Guide 239 Chapter 27 Query Builder To remove a link between objects, right-click the link line and select the Remove item from the context popup menu. Changing join type The join type created by default is INNER JOIN, that is, only matching records of both tables will be included in the resulting dataset. To change join type, right-click the link and choose the join type from "Change type" sub-menu of context popup menu. To define join type and other link properties, right-click the link and select the Properties item from the context popup menu or double-click it to open the Link Properties dialog. 240 MBPM Designer User's Guide Chapter 27 Query Builder Selecting output fields Adding and removing fields and expressions To add a field to the list of query output fields, check the box at the left of a field name in the datasource field list at the Query Building Area. To include all the fields of the specific object you can check the box at the left of the asterisk item in the datasource field list. Also you can drag fields from the Query Building Area to the Columns pane to get the same result. Another way to add a field is to select a field name from the drop-down list of the Expression column in the Columns Pane. Also, you can type any valid expression in the Expression column in the Columns Pane. To add an empty line to the Columns pane, press the Alt+Insert key. MBPM Designer User's Guide 241 Chapter 27 Query Builder To remove a field from the Columns Pane, de-select the checkbox at the left of the field name in the Query Building Area. To move a line in the Columns Pane up and down, press the Alt+Up/Down keys. Also you can add, remove and re-order lines in the Columns Pane using the context popup menu. Working with expressions in the Columns Pane The Output column determines presence of expression in the SELECT list of the query. The Alias column allows you to set aliases for your expressions. Aliases become headings of columns in the result dataset. The Asterisk Symbol 242 MBPM Designer User's Guide Chapter 27 Query Builder Even if you don't select any fields from query datasources, an asterisk item will be added to the select list of result query ("Select * from ..."). By selecting any fields or by adding any output expressions to the query, an asterisk item will be removed from result query (you can add it manually at any time). The asterisk items placed first at the datasource field's list are intended to add all fields from specific datasource, not from all of the datasources ("Select datasource.* from ..."). These asterisk items do not affect the rest of the datasource field check boxes, but act independently. If you want to check all the datasource field check boxes, not the asterisk item, use appropriate items of the datasource context popup menu. Sorting a dataset To define sorting of result dataset, you can use the Sort Type and Sort Order columns of the Columns Pane. The Sort Type column allows you to specify the way the fields will be sorted - Ascending or Descending order. The Sort Order column allows you to setup the order in which fields will be sorted if more than one field will be sorted. To disable sorting by a field, clear the Sort Type column for this field. Defining criteria To define criteria, you can use the Criteria and all of the Or columns of the Columns Pane. In these cells you should write conditions omitting the field itself. For example, to get the following criteria in your query: WHERE (Field1 >= 10) AND (Field1 <= 20) Enter ">= 10 AND <= 20" in the Criteria cell of the Field1 expression. Criteria placed in the Or columns will be grouped by columns using the AND operator and then concatenated in the WHERE (or HAVING) clause using the OR operator. For example, this visual representation will produce the following SQL statement. The criteria for Field1 is placed in the Criteria and Or columns. MBPM Designer User's Guide 243 Chapter 27 Query Builder WHERE (Field1= 10) AND ((Field2 < 0) OR (Field2 > 10)) Some expressions can be of Boolean type, for example the EXISTS clause. In this case you should type "= True" in Criteria column of such expressions or "= False" if you want to place the NOT operator before the expression. Grouping output fields To build a query with grouping, you mark expressions for grouping with the Grouping checkbox. A query with grouping must have only grouping or aggregate expressions in the SELECT list. If you try to set this checkbox for a column without Grouping or Aggregate function set, a Grouping checkbox will be set automatically to maintain validity of result SQL query. When Columns Pane contains columns marked with the Grouping checkbox, a new column called "Criteria for" appears in the grid. This column specifies application of criteria to expression groups or to their values. For example, you have a column "Quantity" with Aggregate function "Avg" in your query and you type the "> 10" in Criteria column. Having the "for groups" value set in the Criteria for column, the result query will contain only groups with average quantity greater than 10, and your query will have the "Avg(Quantity) > 10" condition in HAVING clause. Having the "for values" value set in the Criteria for column, the result query will calculate the Average aggregate function only for records with Quantity value greater than 10, and your query will have the "Quantity > 10" condition in WHERE clause. Building a query with sub-queries Active Query Builder allows building complex SQL queries with Unions, Sub Queries and Derived Tables visually. Navigating the query tree The Query Structure Tree represents the query structure in compact tree-like form. Using it, you can jump to any Union, Sub-query, Derived table and to any part of the query with a single mouse click. This feature is extremely useful in case of complex SQL queries. 244 MBPM Designer User's Guide Chapter 27 Query Builder By setting the appropriate component's options you can set up the tree to hide unnecessary nodes. For example, you can hide Objects and/or Expressions nodes and show only subqueries structure of the query. Working with sub queries This chapter describes working with Sub-queries used in criteria expressions to limit result dataset (in WHERE, HAVING and SELECT clauses). You can add a sub-query as part of the expression or condition in the Columns Pane while editing text in a cell. To add a sub-query, right click at the text position for a new sub-query and select the Insert Sub-query item from context popup menu or type the "(Select)" text to the Expression column, the "= (Select)" or "In (Select)" text to the Criteria column. The curly brackets are necessary. To build a newly added sub-query visually, confirm editing by pressing the Enter key. The corresponding tab is created above the Query Building Area and ellipsis button become visible at the right side of the cell. By clicking on the ellipsis button you'll be switched to a MBPM Designer User's Guide 245 Chapter 27 Query Builder sub-query tab where you can build it visually in the same way as the main query. If the cell contains more than one sub-query, the drop-down list will appear to select the necessary sub-query. You can always get back to the main query and switch to any sub-query or derived table using tabs above the Query Building Area or using the Query Structure Tree. Working with derived tables Derived Table is a sub-query used as a datasource for the main query. To add a derived table, you should right click on the Query Building Area and select the Add Derived Table item from context popup menu. 246 MBPM Designer User's Guide Chapter 27 Query Builder A new object representing the newly created derived table will be added to the query building area, and the corresponding tab will be created for it. This tab allows you to build it visually in the same way as the main query. Another way to switch to the corresponding derived table tab is to right click at the caption of an object representing the derived table and select the "Switch to derived table" item from context popup menu. You can set an alias for derived table the same way as for ordinary database object. You can always get back to the main query and switch to any sub-query or derived table using tabs above the Query Building Area or using the Query Structure Tree. MBPM Designer User's Guide 247 Chapter 27 Query Builder Working with unions Union sub-queries are managed within the Union Panel in the top-right corner of the Query Building Area. Initially there's only one union sub-query labeled with the "Q" letter. All required operations are performed by means of context popup menus. Union sub-queries can be grouped with other sub-queries and joined with different operators (UNION, UNION ALL, EXCEPT, INTERSECT). l To add a new union sub-query, select the New Union sub-query menu item. l To enclose the sub-query in brackets, select the Enclose in Brackets menu item. l l l l To move the sub-query or bracket to the top of the query (the topmost sub-query is the left one), select the Move Left menu item. To move the sub-query or bracket to the bottom of the query, select the Move Right menu item. To remove the sub-query or bracket, select the Remove menu item. To change the union joining operator, select the necessary operator in the list of supported operators in context popup menu. Union Sub-Query operations l Move Left l Move Right l New Union Sub-Query l Enclose In Brackets l Remove Operations with brackets You can perform the following operations: l Move Left l Move Right l Remove Brackets 248 MBPM Designer User's Guide Chapter 28 Filter Editor Chapter 28 Filter Editor The Filter Editor is used to edit filter criteria for a grid control. To create and customize filter criteria, use the and buttons embedded into the control and context menus supported by the editor's elements: Remarks A filter condition group is a set of conditions combined by the same logical operator. The following filter expression contains two groups combined by the logical OR operator: " ([Product] = 'Chang' And [Quantity] > 20) Or ([Product] In ('Tofu', 'Konbu') And [Quantity] < 100)". In the Filter Editor it's represented as follows: MBPM Designer User's Guide 249 Chapter 28 Filter Editor Add Conditions To add a condition to a logical group, do one of the following: Focus on any condition within the group or the group's logical operator and then press INSERT on the keyboard. Click the button for the group. Click the group's logical operator and select Add Condition. To add a group of conditions to another group, do one of the following: l l l Focus any condition within the group or the group's logical operator and then hold down the Ctrl key and click + on the keyboard. Click the group's logical operator and select Add Group. To add a condition or a group of conditions that have been copied to the clipboard, press Ctrl+V. The new condition will be added to the focused group. Delete Conditions To delete a condition, do one of the following: l Focus on the condition and press DELETE or SUBTRACT. l Click on the button. To delete a group of conditions, do one of the following: l Focus on the group's logical operator and press DELETE or SUBTRACT l Click the group's logical operator and select Remove Group. To delete all conditions, do one of the following: l Focus on the topmost logical operator and press DELETE or SUBTRACT. l Click the topmost logical operator and select Clear All. To cut a condition/group of conditions to the clipboard, focus on this condition/the group's logical operator and press Ctrl+X. 250 MBPM Designer User's Guide Chapter 28 Filter Editor Work with Clipboard To copy a condition/group of conditions to the clipboard, focus on this condition/the group's logical operator and press Ctrl+C. To cut a condition/group of conditions to the clipboard, focus on this condition/the group's logical operator and press Ctrl+X. To paste a condition/group of conditions from the clipboard to the focused group, press Ctrl+V. Change a Column in a Filter Condition To change a condition's column, invoke the column list by doing one of the following: l Click the current column. l Focus on the current column via the keyboard and press SPACE or ALT+DOWN ARROW. Then, choose the required column from the list that will be invoked. Change an Operator in a Filter Condition To change a condition's operator, invoke the operator list by doing one of the following: l Click the condition's current operator. l Focus on the current operator via the keyboard and press SPACE or ALT+DOWN ARROW l Then, choose the required operator from the list that will be invoked Edit a Condition's Value To edit a condition's value, click the operand value and type text. To activate the operand value's edit box without changing the value, click the value or focus on the operand value via the keyboard and press F2, SPACE, ENTER or ALT+DOWN To close the active edit box, press ENTER. To discard changes to the value and close the active edit box, press ESC. Compare a Condition's Column with Another Column Do one of the following: l Click the toggle button: l Press CTRL+Q Then, specify the column via the operand value's edit box. l This feature is not supported by default. It must be enabled by setting the ColumnViewOptionsFilter.UseNewCustomFilterDialog property to true. MBPM Designer User's Guide 251 Chapter 28 Filter Editor l This feature is supported by a limited set of operators: =, <>, >, <, >=, <=. Like, Not Like, Between, Not Between, Any Of and None Of. Navigation To focus on a specific filter condition or a group's operator within the Filter Editor, do one of the following: l Click the target element. l Use Arrow keys to move focus via the keyboard. Filter Criteria with Multiple Logical Operators Some filter criteria contain multiple logical (Boolean) operators combining simple filter conditions. To build such criteria via the Filter Editor, first, you need to identify groups of filter conditions. A filter group is a set of simple filter conditions or other groups combined by the same logical operator. You can think of groups as of clauses in a filter expression wrapped by round brackets. Consider the filter criteria: [UnitPrice] = 10 AND [Product Name] Begins with 'A' OR [UnitPrice] = 20 AND [Product Name] Begins with 'B' OR [UnitPice] > 100. In this expression, we'll identify groups by wrapping them with round brackets as follows: ([UnitPrice] = 10 AND [Product Name] Begins with 'A') OR ([UnitPrice] = 20 AND [Product Name] Begins with 'B') OR [UnitPice] > 100. Here you see three groups of filter conditions. Within each group, filter conditions are combined by the same logical operator: l ([UnitPrice] = 10 AND [Product Name] Begins with 'A') l ([UnitPrice] = 20 AND [Product Name] Begins with 'B') l [UnitPice] > 100. This group consists of a single simple filter condition. The three groups are combined by the same OR operator. After filter groups have been identified, the filter expression can be easily built using the Filter Editor. 252 MBPM Designer User's Guide Chapter 29 Introduction to Visual Scripts Chapter 29 Introduction to Visual Scripts Visual Scripts allows you to create sophisticated scripts, without code, by dragging and dropping. Interface A default visual script has the following items: l Start node l Attachment point l End note The following components, identified in the screenshot below, are used when working with Visual Scripts. 1. Visual Script toolbox – a collection of activities for use with Visual Scripts only. 2. Default Visual Script – a modeling tool which enables the user to handle an event without having to write code. 3. Design Area/Main pane of Designer – design area to build your Visual Script. 4. Properties – used to set the properties for the visual script. The properties that determines its behavior. MBPM Designer User's Guide 253 Chapter 29 Introduction to Visual Scripts Types of Visual Scripts There are two types of Visual Scripts: l Event handler visual scripts l Reusable visual scripts Both types of visual script are created in the visual script design interface. The following are events: l When Action Started l When Action Completed l When Stage Started l When Stage Completed Event Handler Buttons Event handler buttons are found in the following locations of a Process in the Designer: l Within event handler properties in Basic and Enhanced mode l Either side of stages and actions in the main pane in Enhanced mode Event Handler Visual Scripts Event handlers appear in two places: l In the main pane of a process in Enhanced view l In the Properties task pane of process and form controls 254 MBPM Designer User's Guide Chapter 29 Introduction to Visual Scripts The event handlers related to processes are graphically represented as buttons. You can toggle the MBPM Options->Process Modeling setting to Enhanced view to view these buttons. Creating a new event handler Visual Script You can create a new event handler visual script in one of the following ways: l Click on the event handler icons on a process l Using the properties task pane. Reusable Visual Scripts This is a script created with the view to reuse them in other visual scripts. Once created, they can be promoted to the Visual Script toolbox. Creating a new reusable Visual Script To create a new reusable visual script: 1. On the Home ribbon tab, Components group, click on the VisualScript button. The Visual Script design interface is opened displaying a default visual script consisting of a start node, a connection point, and an end node. 2. To view the visual script properties, click anywhere on the background in the main pane. The Promote Visual function is collapsed, by default. 3. Click in the Name field and enter a name for the visual script. (You can choose to retain the default name if you wish). 4. To promote the visual script, in the Promote Visual Function field, select the check box. Note: If you are using a promoted visual script within itself, the promoted visual script should only be a part of If/Else condition to avoid creating an infinite loop at run-time. When a visual script is promoted, the following optional properties become editable: l Category l Caption l Tooltip l Icon (graphic picker) 5. To build the visual script, in the Visual Script toolbox, click on an activity and drag it onto the default visual script attachment point. The activity is added to the visual script. 6. Edit the activity's properties. 7. Repeat steps 4 and 5 to add further activities to the visual script. 8. To save the visual script, select the MBPM button > Save. Categorizing a Promoted Reusable Visual Script The Visual Script activities are divided into a number of categories. MBPM Designer User's Guide 255 Chapter 29 Introduction to Visual Scripts To promote a visual script to an existing category: In the properties pane, click in the Category field and select a category from the drop-down menu. The menu displays all core categories plus any others that have been previously defined by the user. The visual script will now be available in the toolbox under the selected category. To promote a visual script to a new (user defined) category: l In the properties pane, click in the Category field and enter a category name. A new category is displayed in the toolbox, and the visual script is now available under that category. If you promote a visual script but do not select a category, the Designer will create a default category with the project's name. The activities do not support in/out or reference parameters as part of method signature. You can however use a simple wrapper to the required method: [Promote(PromotionTargets.VisualToolbox)] [Category("UserCategory")] public static bool SampleActivity(string activityParam, int activityParam2) { return SampleCallByRef(ref activityParam, activityParam2); } private static bool SampleCallByRef(ref string activityParam, int activityParam2) { return true; } Creating Event Handler Visual Script You can create event handler visual scripts either from process in Enhanced view or from the process' properties pane. Enhanced View You can create an event handler visual script from the process in Enhanced view as follows: 1. To enable enhanced view, see MBPM Designer Options > Process Modeling. In the Enhanced view of a process, both actions and stages will display event handler links. 2. For a stage or action in the process, click on the empty event handler button. The Visual Script design interface is opened displaying a default visual script consisting of a start node, connection point, and an end node. 3. To build the visual script, from the Visual Script toolbox, click on an activity and drag it onto the default visual script attachment point. The activity is added to the visual script. 256 MBPM Designer User's Guide Chapter 29 Introduction to Visual Scripts 4. After you drag an activity from the Visual Script toolbox to be placed in the main pane of the Designer, you can attach it to the Visual Script only at the attachment point. The attachment point is indicated with a green plus icon indicating the points where you can drop the activity. 5. Edit the activity's properties in the properties task pane. 6. Repeat steps 4 and 5 to add further activities to the visual script. 7. To save the visual script, select the MBPM button > Save. Properties pane of process You can also add visual script to actions or stages by using the Properties task pane of the action or stage as follows: 1. Click on the empty Event handler button in the stage or action's properties task pane. 2. Follow the steps mentioned above (step 3 to step 7) to create a visual script. After you create your Visual Script, return to the process. The following diagram displays the Properties task pane view when a visual script is created and attached for "When action completed". In the above diagram, you will notice that no visual script is attached for "When action started". Deleting an Event Handler Visual Script To remove an attached visual script that you have set, click on the button in the property. Visual Script Toolbox The Visual Script toolbox contains the following activities that can be used in building a Visual Script. When a activity returns data, that data is auto-created as a variable of the type returned. The name, caption, description, and enabled properties are common to all activities. Name specifies a unique name to identify an activity; caption is the text that is displayed in the activity's block; description describes the activity; and enabled property indicates whether an activity should be executed or skipped. The other properties are described below: Commands Activity Name Assign Value(s) Use this activity to assign one or more new value(s) to specified variable(s). MBPM Designer User's Guide 257 Chapter 29 Introduction to Visual Scripts Property Name Description Assignments Specify set of one or more assignment statements. Example Consider a Folder Search Form with a Refresh button that retrieves the folders created between selected dates. In the Refresh button When button pressed property, drag and drop an Assign Value(s) Activity on to the Visual Script Editor. The Assignments property for the Visual Script can be created to retrieve the folders created between the two dates as follows: 258 MBPM Designer User's Guide Chapter 29 Introduction to Visual Scripts Activity Name Code Activity Use this activity to invoke the Scripting environment. Property Name Description Code Function Write some C# code to execute at this step. Example The following example uses Code Activity to retrieve the properties for chemical elements using a Web Service Connection. Consider that a Web Service Connection exists that retrieves the periodic table for chemical elements. Consider a Form that has been designed as follows: In the Lookup Symbol button’s When button pressed property, drag and drop a Code Activity on to the Visual Script Editor. MBPM Designer User's Guide 259 Chapter 29 Introduction to Visual Scripts Click the Code Function property and enter the code as follows: localhost.PeriodicWS.PeriodicTableLookup.asmx.ElementDetails el = PeriodicTableScript.getElementDetailsBySymbol(Local.txtSymbol); Local.intAtomicNumber = (int)el.AtomicNumber; Local.memMessage = el.Message; Local.numAtomicRadius = (Real)el.AtomicRadius; Local.txtSymbol = el.AtomicSymbol; Local.numAtomicWeight = (Real)el.AtomicMass; Local.numBoilingPoint = (Real)el.BoilingPoint; Local.numDensity = (Real)el.Density; Local.numElectroNegativity = (Real)el.Electronegativity; Local.numIonisationPotenial = (Real)el.IonizationPotential; Local.numMeltingPoint = (Real)el.MeltingPoint; Local.txtElementName = el.ElementName; Local.txtCommonOxidationStates = el.CommonOxidationStates; Note: Data Casting has been used on some of the values returned by the Web Service. For more information, please see Data Casting. Activity Name Write to Log Logs a user-defined message in the MBPM database. Property Name Description Message Specify a brief message to be written to the log (less than 250 characters). Details Specify additional details to be written to the log (no limit to length). 260 MBPM Designer User's Guide Chapter 29 Introduction to Visual Scripts Property Name Description Severity Specify the severity of the logged item. Valid values are: l Severity.Information l Severity.Warning l Severity.Error Note that Severity.Error should contain a value. If it is left blank, the process flow will not be halted and an error message, 'Failed to execute deployed <<method name>>, using entity <<entity name>>', is displayed. Example Consider the following Process that is used for logging information to the database: In the When action completed property for the Write to Log Error, Write to Log Warning, and Write to Log Information actions, drag and drop Write to log activity on to the Visual Script Editor. The Write to log activity properties can be populated as follows for the 3 states as follows: Error: MBPM Designer User's Guide 261 Chapter 29 Introduction to Visual Scripts Warning: Information: The Entry Description message is saved in the eLog table of the database. Activity Name Send E-Mail Send an e-mail. 262 MBPM Designer User's Guide Chapter 29 Introduction to Visual Scripts Property Name Description To Specify a list of one or more recipient email addresses who will receive the emailed message. CC Specify a list of one or more recipient email addresses to be copied in. BCC Specify a list of one or more recipient email addresses to be blind copied in. Subject Write the subject of the message to be emailed to all recipients. Message Write the message to be emailed to all recipients. For sending messages in HTML format, use HTML tags within quotes. Attachments A string identifying the directory path, name and extension of a file to be included as an attachment. If omitted (by using “ ”), no attachment will be included. From Specify the email address of the person who sent the emailed message. Note: To avoid run-time errors from occurring, this property should be set either to empty (i.e. "") or contain an email address which has an acceptable format i.e. "e@mail.address". Example Consider a Process that involves a user action to send an email to Manager of the Originator. MBPM Designer User's Guide 263 Chapter 29 Introduction to Visual Scripts Consider a Form that has been designed as follows for the stage following Submit to Manager action: In the When action completed property for the Submit to Manager action, drag and drop Send Email Activity on to the Visual Script Editor. The property values can be entered as shown in the screenshot below: The information is emailed to the recipient. 264 MBPM Designer User's Guide Chapter 29 Introduction to Visual Scripts Activity Name Raise Flag Use this activity to specify that a Flag is to be raised. This allows one action to raise multiple Flags. Property Name Description Flag Name Name of the Flag created. Folder ID The Folder ID that the Process should look for to receive data. For example, use ProcessContext.FolderParent to ensure that the parent Process listens to the appropriate folder’s Flag data passed from the SubProcess. Parameters The name of the parameter that holds Flag data to be transferred between Processes. A Flag is used to trigger data transfer between folders within or across Processes. They work in combination with flagged actions. Note: There are 2 types of Flags that you can use from the Activities toolbox. The generic Raise Flag activity from Commands category and a Raise <<flag name>> activity from Flags category which is displayed once you create a new Flag component. The example below uses both types of Flags. There are 3 steps to set up a Flag: l Create a Flag l Raise a Flag l Invoke a flagged action Once a Flag has been created from Components category, it can be raised using Visual Scripting. For more information, see Flags. Note: When a Flag is created and parameters are added, deleted or edited later then any existing Flag activities used in a Visual Script will not be automatically updated. To update with the latest Flag definition, the user should remove and re-add the Flag raising activity to the Visual Script. Example Consider a Process designed for the purpose of document review that consists of a review phase and an approval phase. The Review Process and the Approval Process have been defined as separate Processes where the Review Process is the parent and the Approval Process is the child Process (SubProcess). Consider that the ‘Document name’ from the Review Process needs to be passed to the Approval Process and the ‘Approved By’ and ‘Approved Date’ data need to be sent back from the Approval Process to the Review Process. MBPM Designer User's Guide 265 Chapter 29 Introduction to Visual Scripts Sending Flag Data from Parent Process to Sub-Process: 1. Create a Flag: StartApprovalFlag (Parameter: txtDocumentName) 2. In the Review Process, consider the following workflow snippet where the Close Review action transfers control to the Approval Process by raising a Flag: 3. Select the Close Review action and create a Visual Script for the When action completes property. 4. Scroll down to the bottom of the Visual Script Toolbox and drag and drop the Flag Raise StartApprovalFlag from the Flags category to the Visual Script Editor. 5. For the StartApprovalFlag Flag activity, set ReviewProcessData.txtDocumentName as the value for the Flag Parameter property (where ReviewProcessData.txtDocumentName is the Process Data variable of Review Process). This will transfer the control to the child Process to complete the approval and also pass the ‘Document Name’ as the parameter. 6. Create the Approval Sub-Process: 7. In the Properties pane of the StartApproval Action, set the Flag used to invoke this action to StartApprovalFlag: 266 MBPM Designer User's Guide Chapter 29 Introduction to Visual Scripts This ensures that the Sub-Process listens to the Flag raised by the parent Process. 8. In the Properties pane of the StartApprovalFlag Action, click When Action Completed and drag and drop the Assign Value(s) activity to the Visual Script Editor: 9. In the Assignments property, set the value to: ApprovalProcessData.DocumentName = FlagData.txtDocumentName (where ApprovalProcessData.txtDocumentName is the Process Data variable of Approval Process) You can set this assignment by using the Expression Builder: 1. Select the ApprovalProcessData.DocumentName from the variable drop-down box. 2. Choose the FlagData.txtDocumentName listed under Parameters of the Current Flag category. This sends the Document Name data stored as Flag data to the Sub-Process. 10. Create an Approval Form that allows entering the ‘Approved By’ and ‘Comments’ information and associate it to the Ready to Approve stage. Sending the Flag data to Parent Folder: MBPM Designer User's Guide 267 Chapter 29 Introduction to Visual Scripts 11. Create a Flag: PassApprovalDataFlag (Parameters: txtApprover, txtComments) 12. Click the Complete Approval action’s When action completed property, and drag and drop the Raise Flag activity from the Commands category of the Activities Toolbox and set the properties as follows: Note: The FolderID property should be set to ProcessContext.FolderParent to ensure that the parent Process listens to the appropriate folder’s Flag data passed from the Sub-Process. The values entered in the Approval Process Form (Approver and Comments) are passed through the Flag’s Parameters property. These Property settings pass the Flag data (the Approver Name and Comments) entered in the Approval Form from the Review Process (Sub-Process) back to the Approval Process (Parent Process) 13. Back in the parent Review Process, in the Finish Approval action, set the properties as follows: 268 MBPM Designer User's Guide Chapter 29 Introduction to Visual Scripts 14. For the When action completed property of the Finish Approval Process, drag and drop the Assign Value(s) activity to the Visual Script Editor: 15. In the Assignments property, use the Current Flag of Expression Builder to assign values to your parent Process Data variables: ReviewProcessData.txtApprover=FlagData.txtApprover ReviewProcessData.txtComments=FlagData.txtComments MBPM Designer User's Guide 269 Chapter 29 Introduction to Visual Scripts Where ReviewProcessData.txtApprover and ReviewProcessData.txtComments are Process Data variables defined in the parent Process. Visual Scripts Activity Name Evaluate %Script() Use this activity to find the value of an expression written in a previous version of MBPM. Property Name Description Formula Provide the % language expression to be evaluated. Using local variables in Formula property of Evaluate activity is not supported. The MBPM Web Client displays an error message. Example Consider the following Process where a case has been resolved and waiting to be archived. In the When stage started property for this stage, create an Evaluate %Script() activity. 270 MBPM Designer User's Guide Chapter 29 Introduction to Visual Scripts The activity can be used to set to update the status of the case as follows: %Subject:=”Waiting for Archive” Activity Name If Else Use this activity to specify that MBPM is to perform one command if a condition is TRUE, and another if it is FALSE. Further conditional branches can be added if required. Property Description MBPM Designer User's Guide 271 Chapter 29 Introduction to Visual Scripts Name Condition Provide the condition that should be evaluated to determine which branch to execute. Example The following example uses If Else Activity to retrieve the search results based on legalrelated Matter Name or Matter Number. Consider a Form that has been designed as follows: The Search button’s When button pressed property can be used to open the Visual Script Editor and use the If Else activity as follows: The condition for If Else can be set as follows: 272 MBPM Designer User's Guide Chapter 29 Introduction to Visual Scripts PurchaseRequestData1.txtMatterSearchInput <> “ ” The SetSearchParams is an Assign Value(s) activity. The Assignments property has been set as follows: PurchaseRequestData1.txtMatterSearchString=”%”+PurchaseRequestData1.txtMatterSearchInput+”%” Activity Name For Each A loop that executes the specified sequence of activities on each of the items in the specified list or Business Object. Property Name Description List / Business Object Specify the list or Business Object to be looped through. Note: You can use a SELECT statement in For/Each loop. To use the values within the loop, use the name of the activity. For example: MyForEachActivity1[0].ToString() where the number in square brackets is the column number for the data returned by the Select statement. Example The following example uses For Each Loop Activity to retrieve all the items of Business Object and assign the contents to a text box. Consider a Form with a text box designed as follows: MBPM Designer User's Guide 273 Chapter 29 Introduction to Visual Scripts Consider that a Form is associated with Business Object of Query type that retrieves all the Process names as shown in screenshot below: Associate this Business Object with the Form. The text box’s Business Object Item property is set to the following: ProcessContext.ActionNote 274 MBPM Designer User's Guide Chapter 29 Introduction to Visual Scripts Click the Form’s When user loads form property to open the Visual Script Editor. Drag and drop a ForEach Activity and an Assignment Activity within ForEach activity. Set the List/Business Object collection property of the ForEach Activity to BusinessObject11. The Assign Value(s) activity will have the following: This will loop through all the Processes in your Blank Forms list and fill the BusinessObjectParse text box with data separated by each line. Activity Name While Loop A loop that executes whilst a condition is true. Property Name Description MBPM Designer User's Guide 275 Chapter 29 Introduction to Visual Scripts Condition Provide the condition that should be evaluated to determine whether to continue looping. Example Consider that in the above example we want to list all the Processes that have the default language set to “en-US” from a list of Processes that have language property set to “DEFAULT”. To display this filtered list, instead of For Each, use the While Loop in the above example and set the condition as follows: ProcessContext.eLocaleID==”en-US” Document Activity Name Save Attachment Adds a new attachment to the specified folder (saves it in the database) by storing the inmemory data provided. Property Name Description Folder ID Indicate the folder to which the attachment should be saved. File Name Indicate the name of the file to save to the database. Example Consider a Process designed as follows that imports a case file from customers and saves it in Word doc format. In the Import Case action’s When action completed property, drag and drop the Save Attachment activity to the Visual Script Editor and set the following properties for the activity as shown in the example below: l FolderID l File Name 276 MBPM Designer User's Guide Chapter 29 Introduction to Visual Scripts l Attachment The Save Attachment activity saves the attachment in the eAttachment table of the database for the specified Folder ID: Activity Name Get Attachment Retrieves the data for an existing attachment from the database, and saves it to a specified location on disk. Property Name Description Folder ID Indicate the folder from which the attachment should be retrieved. File Name Indicate the name of the file to retrieve from the database. File Path Indicate the directory path of the destination on disk along with file name. Example MBPM Designer User's Guide 277 Chapter 29 Introduction to Visual Scripts Consider a Sub-Process of the above Process that needs to retrieve the attachment that was saved earlier, followed by Assign Value(s) activity to set the file name and subject. To do this, drag and drop the Get Attachment activity to the Visual Script Editor as shown in the example below: In the Properties pane, enter appropriate values for the following properties as shown below: l FolderID l File Name l File Path Activity Name New Attachment Adds a new attachment to the specified folder (saves it in the database) by reading the contents of a file on disk. 278 MBPM Designer User's Guide Chapter 29 Introduction to Visual Scripts Property Name Description Folder ID Indicate the folder to which the attachment should be added. File Name and Path Indicate the directory path and name of the file to attach. Example In the above Process, consider a scenario where a case confirmation details are saved to local computer and a confirmation email sent to the customer. To do this, drag and drop the New Attachment activity followed by Send Email activity in the Visual Script Editor. In the Properties pane, set the following properties for the activity as shown in the example below: l FolderID l File Name l Path Activity Name Delete Attachment Deletes an existing attachment from the database. Property Name Description Folder ID Indicate the folder from which to delete the attachment. File Name Indicate the file name of the attachment to delete. MBPM Designer User's Guide 279 Chapter 29 Introduction to Visual Scripts Example In the above Process, consider a scenario where a case is closed and the attachment can be deleted. To do this, drag and drop the Delete Attachment activity to the Visual Script Editor and set the following properties for the activity as shown in the example below: l FolderID l File Name Activity Name Write to File Use this activity to write text to a file on the server. The text can be the contents of variables or the results of a formula. This can either be a new file, or you can append to an existing file. Property Name Description File Name and Path Indicate the directory path and name of the destination file. Text Provide the text that should be written to the file. Create New File Indicate whether or not a new file should be created and written to. Write As Unicode Indicate whether or not the text should be written to the specified file in Unicode. Example In the above example, consider a scenario where an attachment is being saved to local computer. To do this, drag and drop the Write to File activity to the Visual Script Editor. In the Properties pane, Set the following properties for the activity as shown in the example below: 280 MBPM Designer User's Guide Chapter 29 Introduction to Visual Scripts l File Name and Path l Text l Create New File l Write as Unicode Activity Name Save Folder to File Write the values of all of the folder variables to a comma separated values (csv) file. The first line of the file will consist of field names and the second will consist of values. Property Name Description Folder ID Specify the required folder. File Name Indicate the relevant file name. Delimiter Optionally specify an alternative delimiter to use rather than commas. Example Consider a scenario where the Process’ Folder ID information is being saved to local computer. To do this, drag and drop the Save Folder to File to Visual Script Editor. In the Properties pane, Set the following properties for the activity as shown in the example below: l Folder ID l File Name l Delimiter MBPM Designer User's Guide 281 Chapter 29 Introduction to Visual Scripts Activity Name Delete File Use this activity to delete the specified file from a server. Property Name Description File Name and Path Indicate the directory path and name of the file to delete. Example In the above Process, consider a scenario where a case is closed and the attachment can be deleted. To do this, drag and drop the Delete File activity to the Visual Script Editor. In the Properties pane, set the following properties for the activity as shown in the example below: l File Name and Path 282 MBPM Designer User's Guide Chapter 29 Introduction to Visual Scripts Database Category Activity Name Insert Row Use this activity to insert rows into a database table. Property Name Description Connection Provide a valid connection to the required data source. Insert Command Provide a valid SQL INSERT statement. The INSERT statement has the following structure: "INSERT INTO TABLENAME (TXT_COLUMN1, INT_COLUMN2) VALUES (' "+BUSINESSOBJECT.TXT_VARIABLE1+"', ' "+BUSINESSOBJECT.INT_VARIABLE2+" ')" Example Consider a Form that has been designed as shown below: Click on the Add Item button’s When button clicked property to open the Visual Script Editor. Drag and drop the Insert Row activity along with other Assign Value(s) activities that calculate totals and clear the Form variables. MBPM Designer User's Guide 283 Chapter 29 Introduction to Visual Scripts In the Properties pane of the Insert Row activity, enter the name of the connection in Connection property, and SQL command in the Insert Command property to insert a new row to a table as follows: Activity Name Update Row Use this activity to update a table in a database. Property Name Description Connection Provide a valid connection to the required data source. Update Command Provide a valid SQL UPDATE statement. The UPDATE statement has the following structure: "UPDATE TABLENAME SET TXT_COLUMN1 = '"+ BUSINESS_OBJECT.TXT_VARIABLE1 +"' WHERE (TXT_COLUMN2 = '"+ BUSINESS_OBJECT.TXT_VARIABLE2 +"')" Example Using the same example for Insert Row, click on the Update Item button’s When button clicked property to open the Visual Script Editor. Drag and drop the Update Row activity along with other Assign Value(s) activities that calculate totals and clear the Form variables. 284 MBPM Designer User's Guide Chapter 29 Introduction to Visual Scripts In the Properties pane of the Update Row activity, enter the name of the connection in Connection property, and SQL command in the Update Command property to update a new row to a table as follows: Activity Name Delete Row(s) Use this activity to delete one or more row(s) from a database table Property Name Description Connection Provide a valid connection to the required data source. Delete Command Provide a valid SQL DELETE statement. The DELETE statement has the following structure: "DELETE FROM TABLENAME WHERE TXT_COLUMN1='"+BUSINESS_OBJECT.TXT_ VARIABLE1+"'" Example MBPM Designer User's Guide 285 Chapter 29 Introduction to Visual Scripts Using the same example for Insert Row, click on the Delete Item button’s When button clicked property to open the Visual Script Editor. Drag and drop the Delete Row activity along with other Assign Value(s) activities that calculate totals and clear the Form variables. In the Properties pane of the Delete Row activity, enter the name of the connection in the Connection property, and the SQL command in the Delete Command property to update a new row to a table as follows: Activity Name Execute Stored Procedure Use this activity to execute a database stored procedure which returns NO value. Property Name 286 Description MBPM Designer User's Guide Chapter 29 Introduction to Visual Scripts Connection Provide a valid connection to the required data source. Name of Procedure Provide the name of the stored procedure to execute. Set Parameter Values Provide any parameter values that the stored procedure takes. The value for the Parameters argument can be entered as follows: @MyParam1=My Value1, @MyParam2=My Value 2 The Execute Stored Procedure statement has the following structure: EXEC Stored_Procedure @ParameterName="MyParameter" Example Consider that an Expense Verification stored procedure has already been created that verifies the Expense type selected on the previously designed Form. You can use the SelectSQL command in the Procedure name field to execute the Stored Procedure as follows: Users and Roles MBPM Designer User's Guide 287 Chapter 29 Introduction to Visual Scripts The Users and Roles activities allow you to create, change, and delete users and associate them with roles. The activities are equivalent to making the changes from the MBPM Administrative Tools. Activity Name Add Metastorm User Adds the specified User Name and any additional optional data to the MBPM database. Property Name Description User Name The new user name to be added to the MBPM database. Password The password of the new user to be added to the MBPM database. Reports To The manager(s) of the new user to be added to the MBPM database. Emailed Alerts An email address to which alerts should be emailed for this new user. Email Address An email address for this new user. Distinguished Name The distinguished name of this new user. Example Consider a scenario that requires adding a new user to the MBPM system. Drag and drop the Add Metastorm User activity to the Visual Script Editor. The Properties pane allows you to set the following properties: 288 MBPM Designer User's Guide Chapter 29 Introduction to Visual Scripts Activity Name Update Metastorm User Updates data in MBPM database for the specified user name. Property Name Description User Name The name of the user whose details are to be updated in the MBPM database. Password Optionally specify a new password for the existing user. Reports To Optionally specify a new manager for the existing user. Emailed Alerts Optionally specify a new email address for alerts to be sent to the existing user. Email Address Optionally specify a new email address for the existing user. Distinguished Name Optionally specify a new distinguished name for the existing user. Example Consider a scenario where the Reports to details of the user that was earlier created needs to be changed. For this, drag and drop the Update Metastorm User activity to the Visual Script Editor. In the Properties pane, change the Reports To property from IT Mgr to IT Services Mgr: MBPM Designer User's Guide 289 Chapter 29 Introduction to Visual Scripts Activity Name Delete Metastorm User Deletes the specified User Name and all associated data from the MBPM database. Property Name Description User Name The name of the user to be deleted from the MBPM database. Example Consider a scenario where a user needs to be deleted. For this, drag and drop the Delete Metastorm User activity to the Visual Script Editor. In the Properties pane, enter the User Name to be deleted: 290 MBPM Designer User's Guide Chapter 29 Introduction to Visual Scripts Activity Name Assign User to Role Assigns specified user to specified role. Property Name Description User Name Specify the relevant user name. Role Specify the role to assign. Example Consider a scenario where you want to assign a user to a role. For this, drag and drop the Assign User to Role activity to the Visual Script Editor. In the Properties pane, the User Name and Role property values should be provided: Activity Name Remove User from Role Removes specified user from specified role. Property Name Description User Name Specify the relevant user name. Role Specify the role to remove. Example Consider a scenario where you want to remove the association between a user and the role currently associated to the user. For this, drag and drop the Remove User from Role activity to the Visual Script Editor. MBPM Designer User's Guide 291 Chapter 29 Introduction to Visual Scripts In the Properties pane, the Role property should be provided: Using Standard Activities You can use the following standard activities in your Visual Script to create a workflow: Code Activity 1. Drag and drop the Code Activity from the Visual Script toolbox to the main pane of the Designer. You can only attach the activity to the Visual Script at the attachment point. This is indicated by a small gray-border box appearing below the pointer. 2. Double-click on the code activity to display the code function. Note: If you use Visual Script code activity for working with DataSet, Commit(); should be used to apply data changes. For example: System.Data.DataSet TestDS = TestTable1.Read(); System.Data.DataRow TestRow = TestDS.Tables[0].NewRow(); TestRow[0] = Local.Integer_; TestRow[1] = Local.Real_; TestRow[2] = Local.Text_; TestRow[3] = Local.Check_; TestRow[4] = Local.Currency_; TestRow[5] = Local.Date_; TestRow[6] = Local.Memo_; TestDS.Tables[0].Rows.Add(TestRow); TestTable1.Write(TestDS); TestTable1.Commit(); 292 MBPM Designer User's Guide Chapter 29 Introduction to Visual Scripts TestTable1.CurrentIndex = (TestTable1.Count-1); Conditional l Drag and drop the If Else activity from the Activities toolbox to the main pane of the Designer. Conditional Activity with Multiple Branches l Right-click the outer branch of the IfElse conditional activity and click Add New Branch. Note: The exclamation icons in red indicate that the Boolean condition is not yet set for the expression. When you click on it, the following message is displayed: "Moving a branch left or right" To move a branch left or right, select the inner branch of the IfElse activity and right-click. This provides the option to move the branch left or right. Loop activity l Drag and drop the LoopActivity from the Activities toolbox to the design surface. The exclamation icons in red indicate that the condition is not yet set for the expression. When you click on the icon a warning message is displayed. Transactional Support Transactional support for Visual Scripts ensures that any database changes made using a Visual Script will be rolled back if the transaction does not complete. Transactions include the following operations: l l Refill transaction: It includes all database operations (Database Activities and variables assignments) that occur within a refill. Start Action transaction: It contains all database operations (Database Activities and variables assignments) that occur within 'WhenActionStarted' and ‘WhenUserLoadsForm’ handlers. The handlers take place in following order: l WhenActionStarted l WhenUserLoadsForm l Submit Action transaction: It contains all database operations (Database Activities and variables assignments) that occur within 'WhenActionCompleted', 'WhenUserExitsForm', 'WhenStageCompleted', and ‘WhenStageStarted’ handlers. The handlers take place in following order: l WhenUserExitsForm l WhenActionCompleted l WhenStageCompleted (the stage before an action) l WhenStageStarted (the stage following an action) For example, consider a User Action's 'When action completed' property associated with a Visual Script that performs the following operations: MBPM Designer User's Guide 293 Chapter 29 Introduction to Visual Scripts l A database operation such as ‘Insert Row’, ‘Update Row’, or ‘Delete Row’ activity l A 'Write to Log' activity with Severity property set to Severity.Error In this scenario, the database changes made after executing the 'Insert Row' activity will be rolled back as the 'Write to log' activity fails and the transaction will not be completed. Note: If a transaction fails, only the database operations in that transaction are rolled back. For example, activities from Database group of the Visual Script Toolbox, assignments for variables, and so on, are rolled back. This is irrespective of how the operations were performed - using corresponded Visual Script activities, via code, using promoted functions, and so on. Any operations, which are not connected to the database, are executed regardless of whether the transaction fails or succeeds. For example, Raise Flag, Send Mail, Write to File, Delete File, Get Attachment, and so on are not rolled back. This is irrespective of how the operations were performed - using corresponded Visual Script activities, via code, using promoted functions, and so on. However, transaction may fail because of any operation; not just database operations. Therefore, for example, if a non-database operation such as Write to File operation fails for any reason within a transaction, the transaction will be rolled back. 294 MBPM Designer User's Guide Chapter 30 Introduction to Expression Builder Chapter 30 Introduction to Expression Builder Expression Builder is a tool that allows you to use formulas to build expressions. An expression is composed of one or more formulas. l l A formula is a function that has a return value. Formulas are the building blocks of an expression. An activity is a function that has no return value. It is a building block of a Visual Script. All of the items in the Command category of the Integration Wizard in v7.6 are available as activities in Designer v9. The Expression builder can be accessed from the Properties task pane by clicking on button for any field, which can take an expression. When you click on the Expression Builder button, the Expression Builder is displayed. MBPM Designer User's Guide 295 Chapter 30 Introduction to Expression Builder The Expression Builder has the following areas: 1. Title Bar - Property to which an expression is assigned. 2. Formula Ribbon - Drop-down lists to select formulas 3. Expression Bar - The expression that is being constructed 4. Name of the formula - Formula name that currently has focus as determined by cursor position 5. Parameter Area - Parameters of the formula in the Expression Bar that currently has focus 6. Help Area - Description of the formula The Expression Builder window has buttons to expand and collapse the parameters and help associated with the expression entered. 296 MBPM Designer User's Guide Chapter 30 Introduction to Expression Builder Building Expressions using Intellisense Intellisense in MBPM Designer facilitates auto completion of formulas. Intellisense drop-down list is populated with formulas that are sorted and filtered alphabetically. You can scroll through the list using the keyboard arrow keys or scroll bar and a tool tip displays the highlighted formulas and their parameters. It provides easy access to the formulas as you start typing in the field by displaying a drop-down list of functions that are allowed. If you choose a formula, Intellisense highlights it for easier identification and then prompts you with the correct data type for the argument. Intellisense is displayed even in nested formulas. When you are defining a control on a process form or report, use the Properties editor to specify the properties of the control. For properties that are expression fields, Intellisense is invoked so that you can construct the expression easily from the available formulas. As you start typing, the characters are matched with the formula names and relevant formulas are displayed. OK, Cancel and ESC The OK and Cancel buttons and ESC key can be pressed to exit from both Intellisense and Expression Builder. There are, however, differences in how validation is performed and data is saved, as described in the following table. MBPM Designer User's Guide 297 Chapter 30 Introduction to Expression Builder Key Data Validation OK When the OK button is clicked, an attempt is made to close the Expression Builder (as well as the Intellisense window if it is open) and all changes made by the user are saved. If the expression is invalid, however, a red cross is displayed indicating a validation failure and the Expression Builder remains open, allowing the user to make the appropriate corrections. Cancel Clicking on Cancel causes the Expression builder (as well as the Intellisense window) to close without performing any validation or saving changes. ESC If the Intellisense window is open, pressing ESC closes the window; however, the Expression Builder remain opens. Any changes made whilst in Intellisense are not reflected in the Expression Builder. If Intellisense is not open, pressing ESC acts in the same way as pressing Cancel. Intellisense is available in the following locations: l Expression Editor l Expression Bar l Expression fields within Expression Builder l Script Editor Building Formulas using the Expression Builder You can use the Expression Builder to build expressions using formulas. To access Expression Builder while designing a process: l l Select a user action. In the Properties task pane, for the expression fields (such as Alert message), click on the ellipsis button. The contents of the field are copied to the Expression Bar of the Expression Builder. In this case, the alert message property is of type text and the Expression Builder is displayed in text mode. Once you have opened the Expression Builder, you may type into or edit the existing contents of the Expression Bar. You can also pick a formula from any of the available groups in the Formula ribbon bar. While you are editing an expression in the Expression Builder, Intellisense is invoked. Expression Builder Formulas The following formulas are available in the Expression Builder. 298 MBPM Designer User's Guide Chapter 30 Introduction to Expression Builder AbsoluteNumber Convert the specified number into a positive integer by removing the negation sign and fractional parts (if any). Property Name Description Return Type Number Provide any number to which the Absolute function should be applied. Positive integer AllNotes Return a formatted log of all the notes added to this folder (using the ActionNotes variable) and stored in the eEvents table. Property Name Description Return Type Folder ID Provide the Folder ID related to the set of required notes. List of notes AND Use this logical operator to perform a conjunction on a pair of expressions that return TRUE or FALSE. Property Name Description Return Type Check 1 Provide an expression that evaluates to TRUE or FALSE. Check Check 2 Provide an expression that evaluates to TRUE or FALSE. Check CalculateDateTime Calculate a new date-time the specified number of units before or after the referenced datetime. Property Name Description Return Type Before / After Indicate whether the new date should be before or after the referenced date. Date/Time Count Provide the number of units. Date/Time MBPM Designer User's Guide 299 Chapter 30 Introduction to Expression Builder Property Name Description Return Type From Provide the referenced data-time. Date/Time Units Provide the time unit. Date/Time CalculateDuration Calculate in specified units the interval between the two specified date-times. Property Name Description Return Type From Provide the first date-time. Date/Time To Provide the second date-time. Date/Time Units Provide the time unit in which the calculation should be done. Date/Time Note: "From" and "To" dates used in the above calculation should be in the same scope, that is, both dates should be either process variables or code activity variables but not one of each. For example, refer to the following code snippets: Example 1: //Correct usage //Both variables used in CalculateDuration are defined in code activity Metastorm.Runtime.Types.DateTime dtCurrentTime = Metastorm.Runtime.Types.DateTime.CurrentDate; Metastorm.Runtime.Types.DateTime dtTenMinsAfterCT = Mstm.CalculateDateTime (10, DateTimeUnits.Minutes, DateTimeDirection.After, Metastorm.Runtime.Types.DateTime.CurrentDate); Local.Text1 = dtCurrentTime.ToString(); Local.Text2 = dtTenMinsAfterCT.ToString(); Local.Text3 = Mstm.CalculateDuration(dtCurrentTime,dtTenMinsAfterCT, DateTimeUnits.Minutes).ToString(); Example 2: //Correct usage //Both variables used in CalculateDuration are process custom variables TimeZoneIssueData1.dtCurrentDT = Metastorm.Runtime.Types.DateTime.CurrentDate; 300 MBPM Designer User's Guide Chapter 30 Introduction to Expression Builder TimeZoneIssueData1.dtCurrentDTPlus10 = Mstm.CalculateDateTime(10, DateTimeUnits.Minutes, DateTimeDirection.After, Metastorm.Runtime.Types.DateTime.CurrentDate); Local.Text5 = TimeZoneIssueData1.dtCurrentDTPlus10.ToString(); Local.Text6 = Mstm.CalculateDuration(TimeZoneIssueData1.dtCurrentDT, TimeZoneIssueData1.dtCurrentDTPlus10, DateTimeUnits.Minutes).ToString(); Example 3: //Incorrect usage //One variable used in CalculateDuration is process custom variable while the other one is defined in code activity Local.Text7 = TimeZoneIssueData1.dtCurrentDT.ToString(); Local.Text8 = dtTenMinsAfterCT.ToString(); Local.Text9 = Mstm.CalculateDuration(TimeZoneIssueData1.dtCurrentDT, dtTenMinsAfterCT, DateTimeUnits.Minutes).ToString(); ConcatenateSubstrings If you were to concatenate a variable containing the string "FirstName" with a variable containing the string "LastName", the result would be "FirstNameLastName". Property Name Description Return Type Strings to be Concatenated Provide the list of items that should be concatenated. Text CountCharacters Return the number of characters in a piece of text. Property Name Description Return Type Text Provide the text to which this function should be applied. Positive integer DeleteAttachment Deletes an existing attachment from the database. Property Name Description Return Type File Name Indicate the file name of the attachment to be deleted. Empty string Folder ID Indicate the folder from which the attachment should be deleted. Empty string MBPM Designer User's Guide 301 Chapter 30 Introduction to Expression Builder ExecuteStoredProcedure Use this activity to execute a database stored procedure which DOES return a value. Property Name Description Return Type Connection Provide a valid connection to the required data source. Returns an object Name of Procedure Provide the name of the stored procedure to execute. Returns an object Set Parameter Values Provide any parameter values that the stored procedure takes. Returns an object ExtractSubstring Extract a substring as specified from the supplied text. Property Name Description Return Type Extract From Specify the source text from which the substring should be extracted. Text Number of Characters Specify the length of the substring to be extracted. Text Start Position Specify the position of the first character of the Text substring to be extracted. Findsubstring Attempt to locate a substring within the specified string. Property Name Description Return Type Match Case Indicate whether or not to match the capitalization of the specified substring. Text Start Position Specify the start position from which the search should begin. Text Find Substring Specify the substring to be searched for. Text In Text Specify the source text from which the substring should be found Text Note: Values less than 1 should not be used as Start Position in Find substring function. 302 MBPM Designer User's Guide Chapter 30 Introduction to Expression Builder FormatDateTime Format a date/time value for display. Property Name Description Return Type Date / Time Specify the date-time value. Text Format Indicate the required date-time format. Text The table below shows the accepted date/time formats. BPM does not support format characters like F, D, G. Format Pattern d The day of the month. Single-digit days have no leading zero. (Only if used in the context of a longer pattern. A single "d" on its own represents the Short date pattern.) dd The day of the month. Single-digit days have a leading zero. ddd The abbreviated name of the day of the week. dddd The full name of the day of the week. M The numeric month. Single-digit months have no leading zero. (Only if used in the context of a longer pattern. A single "M" on its own represents the Month day pattern.) MM The numeric month. Single-digit months have a leading zero. MMM The abbreviated name of the month. MMMM The full name of the month. y The year without the century. If the year without the century is less than 10, with no leading zero. (Only if used in the context of a longer pattern. A single "y" on its own represents the Month year pattern.) yy The year without the century. If the year without the century is less than 10, with a leading zero. yyy The year in four digits, including the century. gg The period or era (e.g. "A.D."). This pattern is ignored if the date to be formatted does not have an associated period or era. MBPM Designer User's Guide 303 Chapter 30 Introduction to Expression Builder Format Pattern h The hour in a 12-hour clock. Single-digit hours have no leading zero. hh The hour in a 12-hour clock. Single-digit hours have a leading zero. H The hour in a 24-hour clock. Single-digit hours have no leading zero. HH The hour in a 24-hour clock. Single-digit hours have a leading zero. m The minute. Single-digit minutes have no leading zero. (Only if used in the context of a longer pattern. A single "m" on its own represents the Month day pattern) mm The minute. Single-digit minutes have a leading zero. s The second. Single-digit seconds have no leading zero. (Only if used in the context of a longer pattern. A single "s" on its own represents the sortable time pattern.) ss The second. Single-digit seconds have a leading zero. t The first character in the AM/PM designator. (Only if used in the context of a longer pattern. A single "t" on its own represents the short time pattern.) tt The AM/PM designator. GetEarlierMessage Return the alert message associated with a previous action on this folder. Property Name Description Return Type Message Index Specify the index of the message to be retrieved. Text GetEarlierNote Return the note associated with a previous action on this folder. Property Name Description Return Type Note Index Specify the index of the note to be retrieved. Memo 304 MBPM Designer User's Guide Chapter 30 Introduction to Expression Builder GetEmailAddress Return the email address of a specified user. Property Name Description Return Type User Name Provide the name of the user whose email address is required. Text GetEmailAddresses Return an email address list corresponding to a list of MBPM users. Property Name Description Return Type User(s) Provide the names of the users whose email addresses are required. A list of email addresses (text) GetToDoList Return the list of users who have the specified folder on their To Do lists. Property Name Description Return Type Folder ID Provide the Folder ID related to the required To Do List. A list of strings (text) GetUserAttribute Return one or more attribute(s) of the specified user. Property Name Description Return Type Attribute Specify the attribute(s) of interest. A list of attribute value (text) Relationship Table Specify the relationship or attribute table to be searched. A list of attribute values (text) Selection Criteria Specify the criteria determining which attribute(s) should be returned. A list of attribute values (text) User Name Specify the name of the relevant user. A list of attribute values (text) GetUserDistinguishedName Return a user’s unique ID within a directory. MBPM Designer User's Guide 305 Chapter 30 Introduction to Expression Builder Property Name Description Return Type User Name Provide a valid user name. Text GetWatchList Return the list of users who have the specified folder on their Watch lists. Property Name Description Return Type Folder ID Provide the Folder ID related to the required Watch List. A list of users (text) HtmlToText Convert Rich Text control’s formatted content to a Text control’s unformatted content. Property Name Description Return Type Variable Convert Rich Text control’s formatted content to a Text control’s unformatted content Text Example: Local.PlainText = Mstm.HtmlToText(Local.RTV); Where PlainText is a variable associated with a Text control; RTV is a variable associated with a Rich Text control. IF Use this to check a condition and return the result of the first statement if true or the result of the second statement if false. Property Name Description Return Type Condition Provide the condition that should be evaluated to determine which value to return. Returns an object Value if False The value to return if the condition evaluates to FALSE. Returns an object Value if True The value to return if the condition evaluates to TRUE. Returns an object 306 MBPM Designer User's Guide Chapter 30 Introduction to Expression Builder Note: Currently any expressions in the TRUE or FALSE parameters will get evaluated at runtime regardless of whether the condition is met or not. To workaround this limitation, use the C# conditional statement as follows: <Condition> ? <Value if TRUE> : <Value if FALSE> Left Return the left-hand part of a text string. Property Name Description Return Type Number of Characters Provide the number of characters to be extracted from the left. Text Text Provide the source text. Text List Takes a set of comma-delimited objects of any type and groups them together as a list of objects. Property Name Description Return Type Values Specify the set of items to be grouped together as a list of objects. List ListPublishedRoles Return the list of all published roles. Property Name Description Return Type N/A No parameters. List of text items ListRegisteredUsers Return a list of user names for all users who are registered to use MBPM. Property Name Description Return Type N/A No parameters. List of text items ListSelectedUsers Return a list of users with one or more specified attributes in common. The attributes will be taken from the MBPM attributes table. MBPM Designer User's Guide 307 Chapter 30 Introduction to Expression Builder Property Name Description Return Type Common Attribute(s) Specify one or more attributes that the users have in common. A list of users (text) MaximumNumber Return the largest of a list of numbers. Property Name Description List of Numbers Provide a list of numbers from which the maximum should be determined. Return Type Integer MinimumNumber Return the smallest of a list of numbers. Property Name Description List of Numbers Provide a list of numbers from which the minimum should be determined. Return Type Integer NOT Use this logical operator to negate an expression which returns TRUE or FALSE. Property Name Description Return Type Check Provide an expression which evaluates to TRUE or FALSE. Check Never Use this option to specify that MBPM is to compare or reset time values to 'never'. Property Name Description Return Type N/A No parameters. Date/Time NewAttachment Adds a new attachment to the specified folder (saves it in the database) by reading the contents of a file on disk. Returns attachment name and extension assigned to a new attachment created in the MBPM database. 308 MBPM Designer User's Guide Chapter 30 Introduction to Expression Builder Property Name Description Return Type File Name and Path Indicate the directory path and name of the file to attach. Text Folder ID Indicate the folder to which the attachment should be added. Text OR Use this logical operator to perform a disjunction on a pair of expressions which return TRUE or FALSE. Property Name Description Return Type Check 1 Provide an expression which evaluates to TRUE or FALSE. Check Check 2 Provide an expression which evaluates to TRUE or FALSE. Check Pair Takes a pair of comma-delimited objects of any type and groups them together as a namevalue pair. Property Name Description Return Type Name Specify the name. Name Value pair Value Specify the value. Name Value pair ReadAttachment Retrieves the data as a base 64 encoded string for an existing attachment from the database, for use in memory. Property Name Description Return Type File Name Indicate the name of the file to retrieve. Text Folder ID Indicate the folder from which the attachment should be retrieved. Text ReadFile Read the contents of a text file on the server and place the contents in a text or memo field. MBPM Designer User's Guide 309 Chapter 30 Introduction to Expression Builder Property Name Description Return Type File Name Provide the name of the source file. Text Remainder Calculate the remainder from the dividend/the divisor Property Name Description Return Type Dividend Provide the number to be divided into. Real Divisor Provide the number to be divided by. Real ReplaceSubstrings Find and replace substrings. Property Name Description Return Type New String Specify the substring to put in its place. Text Number of Occurrences Specify the number of replacements to make. Specify 0, if all occurrences should be replaced. Text Old String Specify the substring to be replaced. Text Text Provide the source text. Text Right Return the right-hand part of a text string. Property Name Description Return Type Number of Characters Provide the number of characters to be extracted from the right. Text Text Provide the source text. Text RoundNumber Round a number up to a specified number of decimal places. 310 MBPM Designer User's Guide Chapter 30 Introduction to Expression Builder Property Name Description Return Type Number Specify the number to be rounded up. Integer SaveAttachment Adds a new attachment to the specified folder (saves it in the database) by storing the inmemory data provided. Returns the unique name given to the attachment by the engine. Property Name Description Return Type Attachment Data The attachment's contents. Text File Name Indicate the name of the file to save to the database. Text Folder ID Indicate the folder to which the attachment should be saved. Text SearchDirectory Retrieve information from an LDAP directory search. Property Name Description Return Type Attributes Specify any attributes on which to search. DataContainer Connection Provide a valid connection to the required data source. DataContainer Depth Specify the depth of the search. DataContainer Filter Specify any filters to apply to the search. DataContainer Parameters Specify any parameters on which to search. DataContainer Search Base Specify the base node from which to search. DataContainer SelectSQL Use this formula to run a SELECT statement. Property Name Description Return Type Connection Provide a valid connection to the required data source. Determined by Select statement, one or more MBPM Designer User's Guide 311 Chapter 30 Introduction to Expression Builder Property Name Description Return Type column dataset SQL String Specify a valid SQL Select statement. Determined by Select statement, one or more column dataset UsersManager Use this formula to return the manager, who has a specific role with respect to the specified user. Property Name Description Return Type User Name Specify the name of the user whose manager is required. Text Role Specify the role that the manager should hold. Text Fallback role Specify the role to be returned in the event that the given user has no manager with the specified role. Text UsersStaff Use this formula to return a list of the staff who have a specific role and report to the specified user. Property Name Description Return Type Role Specify the role that each of the staff should hold. Text User Name Specify the name of the user whose list of staff members is required. Text The following method is available in the Expression Builder: GetColumns A method that returns one or two columns of data from a specific Business Object, dependent on the number of columns specified. 312 MBPM Designer User's Guide Chapter 30 Introduction to Expression Builder Property Name Description Return Type Column Specify one or two columns only. List of items or namevalue pairs To use the GetColumns method, use the following notation: <<BusinessObject>>.GetColumns(<<column1>>,<<column2>>,..) For example: BusinessObjectName1.GetColumns("Col1"); or BusinessObjectName1.GetColumns("Col1", "Col2"); Using List Functions Library You can assign an expression to the List options property for Dropdown, List Box, or Memo field. You can do this either by using the Expression Builder or by using a variable which is linked to the List options. The ListFunctionsLibrary provides functions that allow you to return a list that can be used to populate the List options value. The ListFunctionsLibrary.Solution is available in the following location: C:\Program Files\Metastorm\BPM\Sample Processes\ListConversionLibrary You should deploy and add this library to your current project to use these list functions. The following functions are available within the Functions Library: Function Parameters Type Description / Example public static List CreateListFromArray (IEnumerable<string> array) array List A List that is used to populate ListOptions. public static List CreateListFromText (Text input, Text delimiter) input MBPM Designer User's Guide Example Input: A web service response (or auto-created variable from such a response) that returns an MBPM List. List A List that is used to populate ListOptions. Example Input: A web service response (or auto-created variable from such a response) that returns a comma separated list. 313 Chapter 30 Introduction to Expression Builder Function Parameters Type Description / Example delimited List Example input: A comma. public static List CreateListFromXML (string xmlString, string nodeName) xmlString List A List that is used to populate ListOptions. Example Input: A web service response (or auto-created variable from such a response) that returns a xml as a string. nodeName List Example Input: This may be the name of a node whose value(s) you wish to return. public static List GetObjectItems (IEnumerable methodResponse, string propertyIdentifier) methodResponse List (A promoted WebMethod, either expression or auto-created variable from an activity return value.) A List that is used to populate ListOptions that contains the information based on the object & property Identifier. Example: To get all of the phone numbers for a particular employee: GetObjectItems (Connection1.GetEmployeeByID (), "Employee.PhoneNumbers [].Number") propertyIdentifier List (The property whose value(s) should be returned in a list.) Data Types The MBPM type system is a layer in the MBPM architecture stack that can be used as a part of the programmable API for processes. The following data types constitute the MBPM type system. 314 MBPM Designer User's Guide Chapter 30 Introduction to Expression Builder Data Type Description Text Text is the basic text type and similar to the type System.String in the .NET framework. Text does not have a length limit and can be used for any string, including strings with formats such as email addresses or post codes. Integer Integer is the basic ordinal type. Real Real is the basic numeric type. Memo Memo is a text type. It is intended to carry free text entered by the user as a multiline block. Currency Currency is a numeric type. It is a floating point value which is used to carry monetary values. DateTime DateTime is the basic temporal type. DateTime captures date, time and time zone information and is similar to the System.DateTimeOffset type available in .NET. List The List type is an untyped single-dimensional list of objects. It is used as a general purpose list much like ArrayList in the .NET framework. However, it differs from ArrayList in several important ways. l MBPM Designer User's Guide You cannot add to a list, remove from it or 315 Chapter 30 Introduction to Expression Builder Data Type Description change the values on it. l l Lists cast to and from object arrays. List implements IEnumerable<string> and can therefore be used anywhere an enumeration of strings is required. The string enumeration is generated be calling ToString() on each item in the list. In keeping with list and array types in the .NET framework, items on the list are accessed using the [] operator. For example, list1[n] returns the nth item on list1. Any type may be implicitly cast to a list. The result is a list with the operand as single member item. Check Check is a basic logic type and is similar to System.Boolean in the .NET framework. Casting To cast one data type to another, prefix the assignment value with the intended data type in brackets. For example, if you have a number field on a form and if you want to assign it ProcessContext Business Object's CurrentTime, you can do the following: 1. Click on the Expression Builder icon in the Calculation property of the Number field. 2. In the Expression Builder, from the ribbon bar, click Business Object->ProcessContext>CurrentTime. 3. To cast it to a real data type, type (Real) in front of ProcessContext.CurrentTime The expression bar will now display: (Real)ProcessContext.CurrentTime 316 MBPM Designer User's Guide Chapter 30 Introduction to Expression Builder 4. Click OK. The table below indicates all the implicit typecasts available for the types of the MBPM type system, as well as which incur data loss. Implicit Typecasts From Type To Type Result Data Loss Text Memo The string is copied. None. Text Check Blank strings and the values “F”, “False”, “N” and “No” (without case sensitivity) are treated as false, any other string results in true. The actual string value is lost, only the logical meaning is kept. Text List A list with a single item of type Text. None. List Text The string representations of the items in the list are concatenated with new line delimiters. The entire list is represented as a single string in this way. The list structure is lost. It is not possible to distinguish between line breaks that are injected by the cast, and those that exist in the items on the original. The types of values on the list are also lost. List Check An empty list results in false, any other list results in true. The contents of the list are lost. Check Text True results in “True”, false results in “False”. None. Check List A list with a single item of type Check. None. Integer Text The string representation of the value without None. MBPM Designer User's Guide 317 Chapter 30 Introduction to Expression Builder From Type To Type Result Data Loss leading zeroes. Integer Real A floating point value with a zero fractional part. None. Integer Currency A currency value with no fractional part. None. Integer List A list with a single None. item of type Integer. Real Check Zero results in false, The numeric value is any other value are lost. true. Real Text The number is represented as a decimal string. Real Currency The value is retained None. unchanged. Real Integer The value is truncated, the integer part is returned. The fractional part is lost. Real List A list with a single item of type Real. None. DateTime Text The date and time is returned formatted according to the current locale. None, with the exception of the possibility of a small rounding error. DateTime Check A value of zero (origin date) results in false, any other date results in true. The value is lost. DateTime List A list with a single item of type DateTime. None. Currency Integer The value is truncated, only the The fractional part is lost. 318 None. MBPM Designer User's Guide Chapter 30 Introduction to Expression Builder From Type To Type Result Data Loss integer part is retained. Currency Text The value is represented as decimal string using ¤ as a place-holder for a currency symbol. The string is formatted according to locale preferences. None. Currency Real The value is retained None. unchanged. Currency Check A value of zero results in false, otherwise true. The value is lost. Currency List A list with a single item of type Currency. None. Memo Text The string is copied. None. Memo Check A blank string results in false, any other string results in true. The text is lost. Memo List A list with a single item of type Memo. None. Using Operators The operators +, -, * and / take their usual arithmetic meaning between numeric types; + is used as a string concatenation operator for Text and Memo; and the Boolean operators (&&, ||, ==, etc) are used for logic (pseudo code is used in the following sections). Operation Description Integer Division The division of two Integer values yields a double. This differs from the standard .NET integer division which yields an integer. This difference is implemented because it is more intuitive to the user to allow for fractional parts in the result of division. For example given two integers: a=1 and b=2 the user may reasonably expect a/b to evaluate to 0.5 rather than 0. MBPM Designer User's Guide 319 Chapter 30 Introduction to Expression Builder Operation Description List Concatenation The + operator is used as a concatenation operator for lists. Given two lists: a={1,2,3} and b={"hello"," ","world"}, the operation a+b results in the list {1,2,3,"hello"," ","world"}. Note that lists are immutable and this operation does not affect either of the original lists. Instead a new list is created as a result. List Appending The + operator may also be used to append a new item to a list. Logic Operators All fundamental types may be used as predicates in conditional statements. For example it is possible to write an expression using Text && Integer. Given the list a={1,2,3}, the operation a+4 results in the new list {1,2,3, 4}. Any value may be appended to the list except another List. Two lists are concatenated rather than the second list becoming an actual member of the first. Modes of Expression Builder There are several modes of Expression Builder: l Text and Memo Mode – where you can type in or construct textual expression. l Assignment Mode – where you can type in a collection of one or more assign statements. l l l l Condition Mode – where you can construct conditional expressions, in the same way that you can use Condition Builder in v7.6 SQL Mode – where you can use the Select SQL function to return data from your choice of database. List Mode – where you can pass a list of values into a formula. Check Mode – where you can use logical operators AND, OR, NOT and IF to construct expressions. Text and Memo mode Text mode allows you to construct textual expressions. In both Text and Memo modes, the Expression Bar becomes multi-line as you reach the end of a line. 320 MBPM Designer User's Guide Chapter 30 Introduction to Expression Builder Assignment mode The Assignment mode can be invoked from a Visual Script in one of two ways: Using Properties task pane 1. Drag and drop the Assign activity in a Visual Script. 2. Click the ellipsis button of the Assignments property in the Properties task pane. Double-clicking the Assign activity 1. Drag and drop the Assign activity in a Visual Script. 2. Double-click the Assign activity. An Assignment Grid is displayed within the Expression Builder. Adding an Assignment To add an assignment in Assignment mode: 1. Select a variable from the drop-down field on the left hand side. The drop-down only lists editable variables that are currently in context. 2. Enter an expression for the value field on the right hand side. The value field has Intellisense. MBPM Designer User's Guide 321 Chapter 30 Introduction to Expression Builder You can also type a SelectSQL formula in the value field. Note that the value field entry should be enclosed in quotes if the value entered is a text. 3. Click the Add button. Having added a number of assignments, use the arrow key buttons to re-arrange the order, if required. Editing an Assignment To edit an assignment in Assignment mode: 1. Choose the assignment row that you would like to edit from the Assignment grid. The assignment is displayed in the editable row. 2. Edit the assignment. 3. Click the Add button to save your changes. Deleting an Assignment To delete an assignment in Assignment mode: 1. Select the relevant assignment row in the Assignment grid. 2. Click the Delete button. 322 MBPM Designer User's Guide Chapter 30 Introduction to Expression Builder Condition mode You can display the Expression Builder in Condition mode from any property that is expecting a true or false value. For example, the Only start action if property of Flag Action. Adding Conditions 1. In the left hand expression field, enter an expression. 2. Select the required comparison operator from the central drop-down field. 3. In the right hand expression field, enter an expression. 4. Click the Add button. Before you add another condition, you can use the AND or OR operators to combine the conditions. You can select one of these operators from the option buttons to the left of the first expression field. To rearrange the order of conditions, use the arrow key buttons to move the conditions up or down, if required. Editing a Condition To edit a condition: 1. Choose the row that you would like to edit from the conditions grid. The condition is displayed in the top editable row. 2. Edit the condition. 3. Click the Add button to save your changes. Deleting a Condition To delete a condition: 1. Select the condition from the conditions grid. 2. Click the Delete button. MBPM Designer User's Guide 323 Chapter 30 Introduction to Expression Builder SQL Mode You can display the Expression Builder in Select SQL mode by displaying the Expression Builder and then selecting the Database group's Select SQL formula. Alternatively, in the Expression builder's Expression Bar, you can type in SelectSQL. Constructing a simple Select statement To use the SelectSQL formula, enter or select appropriate information as described below: 1. Choose a connection from the list of available connections using the drop-down. 2. Type in the Select query or display Query Builder using the button to build a Select query. The Query Builder is displayed. 3. Construct the required Select statement and click OK. In the above screenshot: 1 represents the Query Builder button. 324 MBPM Designer User's Guide Chapter 30 Introduction to Expression Builder SelectSql Properties Following are the properties of SelectSql() function that can be accessed by typing a dot (.) after the Sql query in the Expression Bar: The following table lists the return value types for the SelectSql() properties. Property Return Value Type Check Check Currency Currency DateTime Datetime GetDataSet Dataset GetDataTable Data table Integer Integer data List List data Memo Memo data Real Real data Text Text data Constructing a Parameterized Select statement There are two ways to construct a parameterized Select statement: l Typing the parameter name in directly l Using Query Builder to add a parameter name For example, if you were constructing the following query: SELECT chkAuthorization FROM ApprovedOrders WHERE eFolderID="APP564"; To type the parameter name directly, do the following: MBPM Designer User's Guide 325 Chapter 30 Introduction to Expression Builder You should use the @ symbol as a prefix to identify a parameter name. Use @Param1 in place of "APP564" in the above query. The query will look as follows: SELECT chkAuthorization FROM ApprovedOrders WHERE eFolderID=@Param1; Tab out of the Select statement field, and a Parameter field is displayed. You can then assign the values to the parameters. Using Query Builder to add a parameter name, do the following: From the Select statement field, display the Query Builder and construct the query as normal. When you want to add a parameter, type the parameter name in the criteria field in the same row as the expression you want to parameterize. In the above example, type in @Param1 in the same row as eFolderID. You can then see the appropriate parameterized clause added to the SQL query. When you return to Expression Builder, a Parameter field is displayed. You can then assign the values to the parameter as in point 1 above. List Mode There are several formulas that take a list of values. l l Number mode:Type in a comma delimited list of numbers into the appropriate property of the Properties task pane. For example, Maximum and Minimum. Text mode: Type a function into the appropriate property of the Properties task pane, which returns a list of values. Following are examples of formulas that return lists: GetEmailAddresses, GetToDoList, GetWatchList and GetUserAttribute. 326 MBPM Designer User's Guide Chapter 30 Introduction to Expression Builder l Conditional mode:Type a function into the appropriate property of the Properties task pane, which returns a boolean value. For example, AND and OR. Using Check Mode You can access all logical operators from the Expression Builder’s Logical group. The available operators are as follows: l AND l OR l NOT l IF Lowercase values ‘true’ and ‘false’ represent logical ‘TRUE’ and logical ‘FALSE’ respectively. Using AND If you select the ‘AND’ operator, two fields - Check 1 and Check 2, are displayed. You can type in conditional expressions into the fields. When you exit a field, the overall conditional expression is generated in the Expression Bar. MBPM Designer User's Guide 327 Chapter 30 Introduction to Expression Builder Using ‘OR’ If you select the ‘OR’ operator, two fields - Check 1 and Check 2, are displayed. You can type in conditional expressions into the fields. When you exit a field, the overall conditional expression is generated in the Expression Bar. Using ‘NOT’ If you select the ‘NOT’ operator, a field named Check is displayed. You can type in the conditional expressions to be negated into the field. Only one expression can be passed to a ‘NOT’ operator so no additional fields appear. After typing in a value, press the TAB key to update the value in the Expression Bar. 328 MBPM Designer User's Guide Chapter 30 Introduction to Expression Builder Using ‘IF’ If you select the ‘IF’ operator, three fields - Condition, Value If True, and Value If False, are displayed. The first field takes a conditional expression (such as Process1.variable = "success") and the second and third fields take expressions or values. For a valid function, the second and third fields must have the same data type. MBPM Designer User's Guide 329 330 MBPM Designer User's Guide Chapter 31 Introduction to Scripting Chapter 31 Introduction to Scripting Scripting allows you to add or extend MBPM functionality by writing your own client or server side scripts. Within the Designer, the Script Editor is used to write server side and client side scripts. The Script Editor provides syntax highlighting for C#. C# Guidelines Following are C# guidelines: Case-sensitivity If you named an item “HelloWorld” (with an upper-case “H”), then it is not the same as “helloWorld” (with a lower-case "h"). The C# compiler will not evaluate a comparison of the above two strings as true as it considers them as two different items. Double-quotes usage All text entries should be enclosed within double-quotes. String Concatenation When working with strings, you will often need to combine two or more separate strings together to form one string. Binding multiple strings together is known as concatenation. Concatenating strings can be accomplished using the concatenation operator. The concatenation operator is the plus sign, + . It is used to signify that one whole string is to be 'added' to another whole string. For example: string s1 = "Business"; string s2 = "Process"; string s3 = “Modelling”; space = “ ”; s1 = s1 + space + s2 + space + s3; This generates the following concatenated string: Business Process Modelling Any mix of string literals and string variables may be concatenated, and you may concatenate as many literals and variables on the same line as you wish. MBPM Designer User's Guide 331 Chapter 31 Introduction to Scripting Note: The space variable used above holds the space character and is used to concatenate spaces in the whole string. Server-Side Scripting You can use the Script Editor to create scripts. C# can be used for server-side scripting languages. However, you can migrate server-side Jscript, VBScript and Jscript.NET files from previous versions of Designer into v9. To create a server-side script, on the Home ribbon tab, Components group, click ServerScript. The Script Editor provides the following features: l Intellisense l Code indenting l Code commenting l Code bookmarking l Code information displaying l Script validation l Keywords color coding Note: The server script class name and constructor name must be unique. Using Business Objects You can use Business Objects on forms and processes as a way to access data from various sources and to bind the data to process and form elements. You can also access and manipulate Business Objects in server script. This allows you to write scripted functions for data manipulation that you can call from Expressions, Events and other Visual Scripts. This help file is intended for people who have at least a basic knowledge of C# and its syntax. It is divided into two parts. The first part deals with how to get access to a Business Object in server script. The second part describes some of the things that you can do with the Business Object once it is available in the scripted code. Passing Business Objects to Scripts To make use of the Business Objects in scripts, you must be able to access a Business Object in a script. This requires passing an instance of a business object to the function. To do this you need to know two things: l How to write a function which accepts a Business Object. l How to get an instance of the Business Object at the point at which the function is called. This section contains the following: l Writing Functions that use Business Objects. l Passing a Business Object Instance to a Function. 332 MBPM Designer User's Guide Chapter 31 Introduction to Scripting l Passing Form Local and Process Business Objects. l Passing a Form or Process Context. Writing Functions that use Business Objects The simplest way to receive a Business Object in a function is to pass it in as an argument in the function call. The following code snippet illustrates this using a method signature. The function takes a Business Object of employee data and returns a formatted employee name for the currently selected employee. [Promote(PromotionTargets.ExpressionBuilder)] public static string FormatEmployeeFullNme(Employees employees) { return string.Format (“{0} {1}”, employees.FirstName, employees.Surname); } This function uses a table Business Object over a solution table of employees. Note that the function's parameter type has the same name as the Business Object. The Business Object ("Employees") is used as the type name for the Business Object parameter. You can apply this method to any custom Business Object. That is, Table, Query and LDAP Business Objects. Process Data Business Objects and the Form's Local Business Object use a different convention. This is covered later. Also note that the Business Object's variables are available as properties of the argument. The properties have the same name as the variables declared for the Business Object. This uses the FirstName and Surname Text variables. Passing a Business Object Instance to a Function Once the function is written, you can call it from an expression. You must have an instance of the Business Object to pass it to the function. When you drag a Business Object onto a form or process, it creates an instance and names the Business Object. It uses the name as the Business Object definition with a numeric suffix, though you may rename the instance after creating it. When you write an expression in the context of a form or process, the Business Object instances are available using these same names. The following illustrates an Employee Business Object bound to a process. From the Data Access, note the instance name Employees1. You can use this identifier in the expression to nominate the instance to pass to the script. MBPM Designer User's Guide 333 Chapter 31 Introduction to Scripting Passing Form Local and Process Business Objects The same technique works for Process Business Objects and the Local Business Objects of a form. However, for these types of Business Object you must identify the Business Object type using a slightly different format. You cannot identify the Business Object type be by its name alone. In this case, use <Form name>.Declarations.Local to identify the Local Business Object of a form. Use <Process name>.Declarations.<Process name>Data to identify a Process Business Object. 334 MBPM Designer User's Guide Chapter 31 Introduction to Scripting The following snippets illustrate these naming conventions for a form called Form1 and a process called Process1. public static void DoSomethingWithLocalData(Form1.Declarations.Local data) { // Use the business object data } public static void DoSomethingWithProcessData (Process1.Declarations.Process1data data) { // Use the business object data } Accessing an instance of these Business Objects when calling the functions behaves the same way as for any other type of Business Object. Passing a Form or Process Context There are a number of other ways to pass a Business Object instance into a script. The main method is to pass an instance of a form or process context and to use the Business Object instances that are associated with them. The following code snippets illustrate functions written to handle a notional Form1 and Process1. This also illustrates accessing Business Object instances from the context object. The identifiers for these objects are the same as the instance names in the BPM project. public static void DoSomethingWithLocalData(Form1 form) // Get a text value from a text variable on the form’s Local data Text t = form.Local.TextVariable; public static void DoSomethingWithProcessData(Process1 process) { Text t = process.Process1Data.eFolderid; Text name = process.Employees1.FirstName; } You must again consider how to obtain an instance of the form or process context to pass it to the function at its entry point. Use the identifier Current for the current context in expressions in both forms and processes. Using Current in an expression on a form returns the form instance. It also returns the process instance when used in an expression on a process. Process Runtime API Reference For process developers wishing to manipulate runtime form content and behavior see the MBPM Process Runtime API Reference in the Appendix. Using the type information that the API reference provides, you can write generalized server script code that operates on instances of all available form field and grid column types. MBPM Designer User's Guide 335 Chapter 31 Introduction to Scripting Using the Business Object’s Refresh Method The Business Object Refresh() method enables a Query Business Object to reload its content by retrieving data from the database. Example Consider a 'Code Activity' that retrieves data into a Grid from a Query Business Object bound to a database table, and then subsequently adds data to the database table. For improved performance, the Query Business Object does not refresh itself by making a call to the database and displaying the newly added data on the Grid. However, if you need to reload the Query Business Object, use the Business Object's Refresh() method as follows: UsersListData1.Refresh(); // UsersListData1 is a Query Business Object Access selected row of Grid To access a selected row of a Grid from the server side, you can use the following: Fields.GridName.SelectedRow["columnName"].ToString() where GridName represents name of Grid and ColumnName represents name of Column. Using the Business Object in Server Script Once the scripted function with access to a business object exists, you can start to use it. This section details some of the functions that you can perform on the Business Object. It covers the following topics: l Reading Variable values. l Setting Variable values. l Reading a DataSet. l Writing a DataSet. l Controlling the Parameters of a Business Object. Reading Variable values To read a variable name from a Business Object read the property of the same name as the variable. Text t = businessObject1.TextVariable; Depending on how your Business Object is set up, and in particular how it is filtered, there may be more than one row of data. In scripted code you can affect which row is selected by assigning to the CurrentIndex property of the Business Object. Read the Count property to determine the number of rows available. The CurrentIndex property is zero-based. Integer count = businessObject1.Count; // Gets the number of rows businessObject1.CurrentIndex = count-1; // Moves to the last row 336 MBPM Designer User's Guide Chapter 31 Introduction to Scripting Setting Variable values As well as reading the values of a Business Object, it is possible to assign values to the variables on the Business Object. Attempting to do this on read-only Business Objects results in a compilation error which prevents validation and deployment. businessObject1.TextVariable = "hello world"; The new value caches on the current folder and flushes to the underlying data store when the current action commits. Reading a DataSet You can get a .NET DataSet object to represent the Business Object's data. This is especially useful for integrating with other components which understand the standard data construct. To get a DataSet object call the Read() method of any Business Object. DataSet ds = businessObject1.Read(); // Gets a standard .NET DataSet object Writing a DataSet It is also possible to assign changes to a Business Object using a DataSet which captures updates. You can do this by writing the updated DataSet to the Business Object using the Write method. DataSet ds = businessObject1.Read(); // Gets a standarad .NET DataSet object /* Make changes to ds */ businessObject1.Write(ds); // Write the changes back to the business object These changes are cached for the current folder instance and are written to the underlying data store when the current action commits. Controlling the Parameters of a Business Object As well as the variables of the Business Object, the parameters are also available as properties. Integer id = businessObject1.IdParameter; However, in the BPM model, Business Object parameters are declarative expressions that are evaluated on demand, rather than values. This means that it is not possible to assign a value to a Business Object parameter in server script. This is, however, still a useful capability to have. It allows the user to write script that uses a Business Object for a lookup based on a filtering parameter. To achieve this type of control over a Business Object parameter in server script, you must bind the parameter to a temporary variable and then assign values to this variable. The technique is illustrated as follows. MBPM Designer User's Guide 337 Chapter 31 Introduction to Scripting l l On the local Business Object (or other temporary store), add a variable for the parameter. On the Business Object that you want to affect, bind the parameter to the variable. You can now assign a value to the local variable to affect the parameter of the Business Object, and therefore the data it returns. public static string GetEmployeeSurname(Form1 form, integer empId) { form.Local.EmployeeId = empID; return form.Employees1.Surname; } 338 MBPM Designer User's Guide Chapter 31 Introduction to Scripting In addition, a form field bound to this same variable allows the end user to control the parameter of a Business Object in the form. Promote Reusable Server-side scripts You can promote Static properties and methods. You can also make them accessible in server side scripts for reuse through the Expression builder and the Visual Toolbox. To achieve this, you need to apply the relevant promotion attributes. One of these attributes is the Promote() attribute, which takes promotion target as an argument. The promotion target argument determines what type of promotion to apply to the method or property. The following table describes the possible values for these arguments. Argument Value Description ExpressionBuilder Causes the method or property to appear on the expression builder ribbon. VisualToolbox Promotes the static methods as a visual activity. Using this on a property has no effect. When you use this as a method, you create a new visual activity with the method parameters displayed as properties. You can write expressions or use any specialized editors associated with the properties to define an expression to fulfill the parameter. None Passing this value to the promote() attribute has no effect. No methods or properties are promoted. All Passing this value to the promote() attribute causes promotion to both the expression builder ribbon and the visual toolbox. If the attributed member is a property, it is only promoted to the expression builder. MBPM Designer User's Guide 339 Chapter 31 Introduction to Scripting Argument Value Description Default This property promotes any method or property to the expression builder and any method as a visual activity. Container Passing this value to the promote() attribute allows the creation of sub-menus to new categories in the expression builder ribbon. If you intend to display the methods and properties as sub-menus, you should use the regular promotion attributes listed previously. You must, however, set their category values to the same value assigned to the container type, otherwise the items are displayed at the top level instead of appearing as sub items. Promotion Attributes You can add the following attributes to provide additional metadata for use by the Designer. This also helps to improve the presentation of the promoted properties and methods. l Category – Groups promoted methods and properties. l Description – Describes what the promoted methods and properties do. l Alias – Names the methods and properties. Default values are provided. Example [Promote(PromotionTargets.ExpressionBuilder)] Category [Category("Folder Information")] You can include a method or property in multiple groups on the expression builder ribbon using the '|' delimiter with the Category attribute. The following illustrates this: [Category("UserCategory|TextFunctions|UserAndRoles")] public static object SampleMethod (string name) 340 MBPM Designer User's Guide Chapter 31 Introduction to Scripting As the previous example indicates, you can include the method or property in existing categories by specifying the name of the standard category. The following lists further examples of standard categories: l Document l NumericFunctions l Logical l TextFunctions l DateTimeFunctions l MetastormDatabase l Directory l BusinessObject l UsersAndRoles l FolderInformation Alias and Description [Alias("Get Stage Priority")] [Description("Returns the priority (order sequence number) of the given stage for a given process.")] public static Integer GetStagePriority( [Alias("Process Name")] [Description("The name of the process the stage is located within.")] Text ProcessName, [Alias("Stage Name")] [Description("The name of the stage of which the priority should be returned.")] Text StageName) The following illustrates the use of the attribute values in the Designer UI. MBPM Designer User's Guide 341 Chapter 31 Introduction to Scripting Note: You cannot use ProcessData Business objects as parameters in functions promoted to the Visual Toolbox. Use of ProcessData Business object in visual scripts prevents deployment of the process. However, this is not the case when using them with the Expression Builder. Client-Side Scripting Either VBScript or JScript can be used as client side scripting languages. Note: JScript is the recommended scripting language as this is the most portable across different browsers. Please refer to the MBPM Web Client User's Guide for specific web browser limitations. Client scripts cannot access MBPM functions and variables directly. Client-side scripts allow a form designer to create custom form functionality by manipulating form properties and form fields. Client-side scripts can either be created as part of a form/field event (i.e. When Button Pressed) or as a standalone script that can be reused within multiple events. To create a standalone client-side script: l On the Home ribbon tab, Components group, click on the ClientScript button. A default Client Script is displayed. The Script Editor provides the following features: l Intellisense l Code indenting l Code commenting l Code bookmarking l Code information displaying 342 MBPM Designer User's Guide Chapter 31 Introduction to Scripting l Script validation l Keywords color coding Features GetField & SetField To provide access to field values, there are two methods for client scripting: getField and setField. function getField(FieldName : string; Attribute : string) : string; procedure setField(FieldName : string; Attribute : string; Value : string); These methods provide access to field values and can be called from JScript or VBScript. When using SetField, the attribute parameter is currently ignored, but will provide access to other field attributes in the future. The eworkSetField and eworkGetField functions are also available to support backward compatibility. Limitations Client-side scripts have no access to MBPM functions. You cannot use the setField and getField client-side scripting methods with Grid or Clip form objects, due to the nature of these objects. SetField Syntax The following table shows required values and examples for each supported control type. Control Accepted Value(s) Example Checkbox Selects the check box if the value matches one of the following: JScript : l checked l check l true l 1 Values are not case-sensitive. All other values de-select the check box. Listbox Comma-separated list or for JScript, a JavaScript array can be used. setField ("Check1", "", "true"); VBScript : setField "Check1", "", “true” JScript : setField("List1", "", "Option2, Option3"); VBScript : setField "List1", "", "Option1, MBPM Designer User's Guide 343 Chapter 31 Introduction to Scripting Option2" Dropdown A string that matches one of the options. JScript : setField ("Dropdown1", "", "Option2"); VBScript: setField "Dropdown1", "", "Option3" DateTime A Date object. JScript : setField ("DateTime1", "", "1967-0707T01:01:01"); VBScript: setField "DateTime1", "", "1971-1117T01:01:01" Number A floating point number. JScript : setField ("Number1", "", "1234"); VBScript: setField "Number1", "", "4321" Currency A floating point number. JScript : setField ("Currency1", "", "12.34"); VBScript: setField "Currency1", "", "43.21" Radiogroup The name of one of the options in the radio group. JScript : setField 344 MBPM Designer User's Guide Chapter 31 Introduction to Scripting ("Radiogroup1", "", "Option2"); VBScript: setField "Radiogroup1", "", "Option3" Signature A text value. JScript : setField ("Signature1", "", "Sample text"); VBScript: setField "Signature1", "", "Sample text" Memo A text value. JScript : setField ("Memo1", "", "Sample text"); VBScript: setField "Memo1", "", "Sample text" Text A text value. JScript : setField("Text1", "", "Sample text"); VBScript: setField "Text1", "", "Sample text" Rich Text A text value. This can include HTML tags. JScript : setField ("RichText1", "", "<h1>Sample text</h1> <br>"); VBScript: setField "Text1", "", "<h1>Sample MBPM Designer User's Guide 345 Chapter 31 Introduction to Scripting text</h1> <br>" Person A valid user name from the list of users displayed in the Users tab of the MBPM Administrative Tools. Note: The name that is displayed following getField and setField operations is the distinguished name of the user. (The value that is used to get and set, however, is the user name). JScript : setField ("Person1", "", "User1"); VBScript: setField "Person1", "", "User1" Note: For drop-down and list controls with Name/Value pairs, the setField function expects the value to be a parameter to the function to correctly update the field. For example: Consider a list containing key value pairs that have been defined as follows: ListItems(Pair("True",1),Pair("False",0)) To set the value of Dropdown1 to "True", use setField as follows: setField("Dropdown1", "", 1); You can use the value stored in 'selection' to set the value of another field. For example: setField("txtName","",selection); GetField Syntax The following table shows the attribute names, associated field types, return values, and examples for the getField method. All examples are valid for JScript and VBScript. Note: Attributes are not case sensitive. Attribute Field Type Return Values Example [empty], no parameter All The field value. getField (“Text1”) In the case of drop-down and list without Name/Value pairs it similarly returns the value. getField (“Text1”, null) Note: ( name and value are the same in this scenario). For drop-down and listbox controls with a Name/Value pair, it returns the value. index Dropdown Listbox Returns a zero-based selected index for drop-down, listbox, Radiogroup and radiogroup controls. getField (“RadioGroup1”, “index”) Returns -1 for all other field types. 346 MBPM Designer User's Guide Chapter 31 Introduction to Scripting fieldtype Label A string is returned (see following list). “Label” Image “Image” Rule “Rule” Button “Button” Edit “Edit” Date “DateTime” NumEdit “Numeric” Combobox “Combobox” Radiogroup “Radiogroup” Checkbox “Checkbox” Memo “Memo” Attachment “Attachment” Grid “Grid” Listbox “Listbox” Password “Password” Signature “Signature” DateTime “DateTime” Time “DateTime” Currency “Currency” Status “Status” DynamicUrl “DynamicUrl” getField (“Currency1”, “fieldtype”) AttachmentGrid “AttachmentGrid” fieldid Person “Person” Invalid Control “Unknown” All MBPM Designer User's Guide Returns the field tab index. getField (“DateTime1”, “fieldid”) 347 Chapter 31 Introduction to Scripting fieldname All Returns the field name. getField (“Dropdown1”, “fieldname”) style All Returns one of the following values to represent the field usage: getField(“List1”, “style”) top All l Hidden l ReadOnly l Mandatory l Optional Returns the position of the object relative to the top of the next positioned object in the document hierarchy. getField (“Memo1”, “top”) left All Returns the position of the object relative to the left edge of the next positioned object in the document hierarchy. getField (“Number1”, “left”) width All Returns the width of the object. getField (“Radio1”, “width”) height All Returns the height of the object. getField (“Signature1”, “height”) caption All Returns the field caption. getField (“Text1”, “caption”) status Status Returns one of the following values to represent the current state of a status field. getField (“Status1”, “status”) Items Dropdown ListBox l SAFETY l WARNING l DANGER Returns a comma-separated list of options. getField (“Dropdown1”, “Items”) Returns the name element of a Name/Value pair. getField(“List1”, “displayName”) RadioGroup displayName Dropdown Listbox 348 MBPM Designer User's Guide Chapter 31 Introduction to Scripting value All Returns the value. Returns the value element of the Name/Value pair for listbox and dropdown controls. getField ("List1","value”) getField ("List1","”) Note: Avoid using invalid attributes. When using invalid attributes, the current field value is returned as a string. However, this may cause unexpected behavior if you introduce the attribute in the future. For example, if the specified field exists, it returns a value: var selection = getField("Dropdown1","AnyNonExistantorInvalidAttribute"); If the specified field does not exist, it returns an empty string. var selection = getField("FieldNameNonExistant","value"); Grid Functions The following client side script functions are provided specially for grids: function getCurrentRow(Grid : string) : number; function getCurrentCol(Grid : string) : number; function getRowCount(Grid : string) : number; function getCell(Grid : string; Col : number; Row: number) : string; function setCell(Grid : string; Col : number; Row: number; Value : string); getCurrentRow This method returns the index of the selected row in the underlying dataset. In the cell exit event handler, it returns the row that has just been left, rather than the one being entered. This index is zero-based and is based on the whole dataset rather than the current displayed page. Note: In releases prior to 7.5, calls to eWorkGetCell (using the result from eWorkGetCurrentRow) were not returning correct data. To resolve this problem, eWorkGetCurrentRow has been changed in Release 7.5 to return an index based on the whole dataset rather than the current displayed page. getCurrentCol This method returns the index of the currently selected column. In the cell exit event handler, it returns the column that has just been left, rather than the one being entered. This index is zero-based. getRowCount This method returns the number of rows in the grid, excluding the header. getCell This method returns the string value of the cell specified by the zero-based Col and Row. MBPM Designer User's Guide 349 Chapter 31 Introduction to Scripting setCell This method sets the value of the cell specified by the zero-based Col and Row. Note: Read-only grids viewed in the Web Client can be paged. In the case of a paged grid, the Row Count refers to the number of rows in the grid as a whole rather than number of rows in the current page. In the same way, the Row index refers to the index row’s index in the grid as a whole, not in the current page. showSubmit and showCancel Functions The following client-side script functions are provided for showing and hiding the Submit and Cancel buttons on a form: procedure showSubmit(Visible : boolean); procedure showCancel(Visible : boolean); showSubmit This function provides the ability to show or hide the Submit button. For example, the Submit button could be hidden until valid data has been entered in the form. showCancel This function provides the ability to show or hide the Cancel button. submitForm, cancelForm and buttonClick Functions The functions listed in the following table provide the ability to customize form behavior. Function Example usage Description Replicates Action submitForm (Event Handler) On field exit 'submitForm()' Use this function to cause the form to submit from the script. Clicking the Submit button. Use this function to cause the cancellation of the form from the script. Clicking the Cancel butt- cancelForm (Event Handler) On field entry 'cancelForm()' 350 MBPM Designer User's Guide Chapter 31 Introduction to Scripting Function Example usage Description Replicates Action on. buttonClick (Event Handler) When button pressed - 'buttonClick ("commandbutton")' MBPM Designer User's Guide Use this function to provide the ability to programmatically click any button on a form. Clicking a Command button. 351 352 MBPM Designer User's Guide Chapter 32 Introduction to Flags Chapter 32 Introduction to Flags Flags are a type of triggering mechanism used by processes to allow communication: l From one process to one or more other processes within the same project. l From a process in one project to one or more other processes in a different project. Flags should be used in conjunction with Flag Actions to trigger updates to one or more existing folders, or to create new folders (as in the case of Sub-processes). When a flag is raised, one or more data items may also be passed to each folder that is waiting for that flag. This data is known as Flag Data. Flags and the flag data they pass are defined through the Flags list. Flags may be raised within a process (internal flags), or by the use of commands external to the process (external flags). When a flag is associated with an action, the specified event is triggered when a folder meets the process's criteria. It is also possible, although much less common, to create a formula to raise a flag from a stage. Flags may be associated with the appropriate action in the following ways: l Raised through an action’s Folder Which Must Raise the Flag property. l Raised through formulas in the Only Start Action if property. l Raised automatically as part of a Sub-process stage and used to display another process, but with no sharing of data. Creating a Flag To create a Flag: 1. On the Home ribbon tab, Components group, click on the Flag button. The New Flag tab is displayed. When you create a new flag, its data consists of one default parameter called Name, whose value is the name of the flag. 2. Click on the blank row to add a new row. A new flag (with the name Flag1) is created in a tab in the Designer. MBPM Designer User's Guide 353 Chapter 32 Introduction to Flags 3. In the Description field, enter a brief description of the flag. The description is useful when you are using several flags in a project or are using the same flag across multiple projects. 4. In the Name field type a name for the parameter. A parameter name cannot be longer than 31 characters, and may only include letters (A-Z or a-z), numbers (0-9), underscores, hyphens. In addition, a parameter name cannot begin with a digit. 5. In the Type field select a flag type from the drop-down list. The options are: Text Check Currency DateTime Memo Integer Real 6. Click the MBPM button > Save. Note: Use unique flag names; flags will affect all deployed processes thus those that unintentionally share a flag name will have unexpected results. Note: The flag name must not just be unique within a project, but also unique across any referenced external projects. If you have a flag defined in the sending process, you need a flag action of the same name defined in the receiving process in order to use the flag to activate a flag action in the receiving process. Raising a Flag After a flag has been defined it can be raised from within a process or from an external application. To raise a flag: 1. Select an action in the process. 2. In the Do this section of Properties pane, click on the Activate Visual Script Eventhandler button associated with either When action started or When action completed. In the Visual Scripting interface, from the flags section of the Activities toolbox, you will find activities for the flags that you have created. 3. To raise a flag, do one of the following: n 354 Drag and drop the Raise a Flag activity from the Commands section of the Activities toolbox in to the Visual Script. This generic approach is analogous to the Raise Flag formula in Version 7 of the Designer. MBPM Designer User's Guide Chapter 32 Introduction to Flags n n n Place a Code Activity from the Visual Scripts toolbox on the Visual Script Editor, double-click the Code Activity, and enter the following: Flags.<<Flag Name>> ("<<Parameter value>>"); Specific flag: This approach is strongly-typed and is the recommended way to raising flags. This can be achieved by dragging and dropping the flag activity for the flag you want to raise at the attachment point. Example syntax for referencing a specific flag would look something like sampleFlagData.MyParameter1 Generic flag: This approach is weakly-typed and will typically be used when it is not possible to access an instance of a flag (for example, when the flag exists outside the project). Example syntax for referencing a generic flag would look something like: sampleFlagData[1] 4. Select the Flag in the Visual Script and set the Flag parameters from the Properties pane. Using eraiseflag.exe to raise a flag from an external application The program eRaiseFlag.exe can be used by any external application or any user to raise a flag outside of MBPM. If you need to raise more than one flag at a time, you can create a .bat file to automate this command line tool. Syntax The syntax for eRaiseFlag.exe is as follows: eRaiseFlag.exe /FlagName:<name> /FlagFolder:<folder id> /FlagData:<flag data> /ServerName:<server name> Switches The following table lists switches used with eRaiseFlag.exe. Switch Example Description /FlagName This switch is required to select eRaiseFlag.exe. This switch defines the name of the flag you want to raise. eRaiseFlag.exe /FlagName:firstname1 This raises the flag named “firstname1.” /FlaeRaiseFlag.exe You may specify a folder in order to move gFolde- /FlagName:firstname1 only that folder. r FlagFolder:0000000000000000000000000000034 This raises the flag “firstname1” and affects only the folder with the folder ID of “0000000000000000000000000000034”. If the folder ID exceeds 31 MBPM Designer User's Guide 355 Chapter 32 Introduction to Flags Switch Example Description characters, errors are displayed and the folder is not moved. /FlagData /FlagName:firstname1 “/FlagData:data1 data2 data3” This raises the flag “firstname1” with three flag data items: “data1,” “data2,” and “data3.” /Serve- eRaiseFlag.exe rName /FlagName:firstname1 /ServerName:metastormbpm This raises the flag “firstname1” on the server named “metastormbpm.” /? eRaiseFlag.exe /? You may define any flag data to be passed along with the flag. If more than one piece of flag data is to be passed they are delimited with tabs. If you are passing multiple amounts of flag data, the entire switch must be encapsulated in double quotes. If you are running eRaiseFlag.exe on a machine other than that of the MBPM Process Engine, you must specify the computer name of the system running the MBPM Process Engine. In order to raise a flag from one machine to another you must have appropriate DCOM rights to the server running the Engine. The syntax of the command may be displayed using the /? option. Receiving Flag Data If a flag passes flag data, the flagged action receives the array of data and can act upon it. Where the flag data is used within the process, its values must be assigned to Custom or Designer Business Objects. The following is an example of consuming flag data: 1. Create a Flag action in your process. 2. Associate the flag that you created with a Flag action using the Flag action Properties pane. 3. On the Extra section of the Properties pane, select the Flag used to invoke this action to allow selection of a previously defined flag from the drop-down list. The Folder tasked with raising the flag option determines which folder must raise the flag for this flagged action to respond. The following table describes the options available: Flag Option Description Any Folder Use this option when the action should be involved 356 MBPM Designer User's Guide Chapter 32 Introduction to Flags Flag Option Description irrespective of which folder raises the flag. This option should always be used for an action that creates a new folder. This Folder This flagged action will only start if the Folder ID in Flag Raiser matches the Folder ID of the folder upon which the flag is acting. This Folder's Parent Use this option in the case of a linked process, when the action should be invoked only as a result of a flag raised by the folder's parent folder. Expression If you choose Expression as your option, an Ellipse button is enabled allowing you to create an expression using the Expression Builder. The expression can be used to dynamically specify the Folder ID that must be listened for. 4. In the Do this section of the Properties pane, click on the Activate Visual Script Eventhandler button associated with When action completed. Associating Flag Data to a Business Object Flag data can be associated to your Business Objects in two main ways. First method: 1. In the Visual Scripting interface, from the Activities toolbox, drag and drop the Code Activity to the attachment point in the Visual Script. 2. Double-click the Code Activity and assign the value of the Flag data to your Business Object. 3. You can assign the values via code, for example: sampleBusinessObject.txt = this.sampleFlagdata.MyParameter1 MBPM Designer User's Guide 357 Chapter 32 Introduction to Flags for the strongly-typed implementation or sampleBusinessObject.txt = this.sampleFlagdata[1] for the weakly-typed implementation where: A Business Object called sampleBusinessObject and a corresponding text control is already defined in your process. SampleFlagdata is the flag that you created in your process. Second Method: 1. In the Visual Scripting interface, from the Activities toolbox, drag and drop the Assign Value(s) Activity to the attachment point in the Visual Script. 2. Double-click the activity to open the Expression Builder. 3. Select the Business Object you wish to assign the Flag Data to, in the image below this is Process1Data.Variable4. 4. Assign the value by selecting the Current Flag Item from the Expression Builder Ribbon and then selecting the relevant parameter. 358 MBPM Designer User's Guide Chapter 33 Introduction to Reports Chapter 33 Introduction to Reports Reports provide the means for business users to display information about the operation of their business processes. The Designer gives you a full range of features for designing reports. Users can run reports in the Web Client interface. Note: Reports do not support multiple Business Objects. Creating a Report To create a new report, on the Home ribbon tab, Components group, click Report. Reports Interface The Designer creates a default report in the main pane and assigns a default name. The reports interface, by default, consists of: l A report filter area l A report detail area MBPM Designer User's Guide 359 Chapter 33 Introduction to Reports In the above screenshot: 1. Represents Filter Area - you can drag and drop filter controls here 2. Represents Report Area - you can drag and drop report controls here Note: If you add several controls to the filtering area of a report and decrease the size of the filter area to display a vertical scroll bar, during deployment, the scroll bars are not visible and instead the controls are displayed on the reporting area. Note: Filters for a report cannot contain duplicate values. Adding new bands You can add more bands to the Report by using the Layout tab of Reporting tools. 360 MBPM Designer User's Guide Chapter 33 Introduction to Reports To add a band: 1. Click the Layout tab under Reporting Tools. 2. Click on the desired band in the Layout tab. Report Group Report Group is a component that allows you to create a grouping of your reports. To create a Report Group: l In the Home tab, Components group, click Report Group. A Report Group is displayed in the Inventory. Also, a tab is displayed in the main pane to set the name, caption, and a default group for your new Report Group. If you select the default report group, then all the new reports that you create will be added to this group. You can use the Grid tools tab to insert, delete, move or delete Report Groups. Moving Reports among Report Groups In the Inventory, you can drag and drop reports between the report groups. Deleting Report Groups In the Inventory, you cannot delete a Report Group without deleting the reports that it holds. Reports Toolbox Report filters and Report controls are added to reports via the Reports Toolbox. The Reports Toolbox will automatically be displayed by default when a report is active in the Designer. To toggle the Toolbox on and off, select the View ribbon tab and click on the Toolbox button. The Report toolbox is divided into four sections: l Default - The Pointer allows you to select a particular report control. l Filter Controls - The controls can be used in the report filter area. l Report Controls - The controls can be used in the report header, detail and footer areas. l Business Objects - The Business Objects can be used in the report filter area. Report Bands A Report Band represents a specific area on a report, which is used to define how to render report controls which belong to it. MBPM Designer User's Guide 361 Chapter 33 Introduction to Reports Except for the Detail band, which is mandatory, bands can be added and deleted from the report. Click on the bands to add it to a report: Report Band Description Top Margin Use this to display auxiliary information, for instance, the report date or any other information required on the top margin of each page. Report Header Located at the beginning of a report. Use this band to display introductory information, for example, a cover page for a report. Page Header Located at the top of every page, below the Report Header band. This band displays page numbers or table headers for a table that continues from the previous page. Group Header Use this for specifying grouping criteria and displaying information at the beginning of a group of records. Group Footer Use this for displaying information at the end of a group of records. Page Footer Located at the bottom of every page, below the Bottom Margin band or Report Footer band. This band displays page numbers or a table footer that continues on the following page. 362 MBPM Designer User's Guide Chapter 33 Introduction to Reports Report Band Description Report Footer Use this to display information once at the end of the report. The report footer can include information such as report summary, grand totals and any other conclusions based on the report. Bottom Margin This displays information on the bottom margin of every page. Report Controls Report controls can be placed in the report area (header, detail and footer areas). They cannot be placed in the filter area. Control Icon Description Chart Inserts a chart into the report. Checkbox Puts a check box on the report. Not user interactive. It just displays a boolean result. Hyperlink Puts a hyperlink on the report. Label Puts a label on the report. PageBreak Inserts a page break into the report. PageInfo Enables the user to add page information to the report. Panel Provides an area into which you can group controls to keep them together. Image Inserts an image into the report. MBPM Designer User's Guide 363 Chapter 33 Introduction to Reports Control Icon Description Memo Inserts a memo filed on the report. Shape Inserts a shape into the report. Grid Puts a table on the report. Report controls and their properties The following tables list all the report controls and their properties. Bottom margin band Property Name Description Color Choose a background color for this band Font Color Choose a font color for this band Height Specify the height, in pixels, of this control. Keep together If set to true, the contents of the entire band will be kept on a single page. Name Specify a unique name to identify this control. This name is not visible at runtime. Notes Use this to enter any specific notes for anyone using this control within the Designer environment. Visible Whether or not this control should be visible. 364 MBPM Designer User's Guide Chapter 33 Introduction to Reports Checkbox Property Name Description Caption Choose a caption for this control. Normally it is the caption which is visible at runtime. Caption alignment Choose the alignment (left, center, right) for the caption the user will see for this control Check State Determines the state of the checkbox Height Specify the height, in pixels, of this control. Keep together If set to true, the contents of the control will be kept on a single page Name Specify a unique name to identify this control. This name is not visible at runtime. Notes Use this to enter any specific notes for anyone using this control within the Designer environment. Position from left The position (in pixels) of this control, from the left hand side of the process design surface Position from top The position (in pixels) of this control, from the top edge of the report area Variable select a Business Object variable that will be used to populate the checkbox Visible Whether or not this control should be visible. MBPM Designer User's Guide 365 Chapter 33 Introduction to Reports Property Name Description Width Specify the width, in pixels, of this control Word wrap Wrap text in this control Detail band Property Name Description Color Choose a background color for this band Font Color Choose a font color for this band Height Specify the height, in pixels, of this control. Keep together If set to true, the contents of the entire band will be kept on a single page. The Keep Together property specifies whether the contents of the band can be horizontally split across pages. In other words, if the content of the band is larger than the remaining space on the page, this property specifies whether the band's content should be split across the current page and the next page, or whether the band will be printed in its entirety on the next page. This property is in effect only when a band's contents don't fit onto the current page. If the band still can't be printed in its entirety on the next page (there isn't enough space to keep all the band contents together), then it will be split as though this property's value is set to false. Name 366 Specify a unique name to identify this control. This name is not visible at run-time. MBPM Designer User's Guide Chapter 33 Introduction to Reports Property Name Description Notes Use this to enter any specific notes for anyone using this control within the Designer environment. Visible Whether or not this control should be visible. Grid Property Name Description Border color Choose a border color for this section Border color Choose a border color for all rows Border color Choose a border color for even rows Border color Choose a border color for odd rows Border width Border width for this section Border Width Select the width for the border for all rows Border Width Select the width for the border for even rows Border Width Select the width for the border for odd rows Borders Choose what borders should be displayed Borders Select what borders should be displayed for all rows Borders Select what borders should be displayed for even rows Borders Select what borders should be displayed for odd rows MBPM Designer User's Guide 367 Chapter 33 Introduction to Reports Property Name Description Bottom Select the size of the padding to the bottom for all rows Bottom Select the size of the padding to the bottom for even rows Bottom Select the size of the padding to the bottom for odd rows Color Choose a background color for this control Color Choose a background color for all rows Color Choose a background color for even rows Color Choose a background color for odd rows Even Style Select an existing style or create a new style Font Choose a font for the grid Font Choose a font for all rows Font Choose a font for even rows Font Choose a font for odd rows Font color Choose a font color for this grid Font Color Choose a font color for all rows Font Color Choose a font color for even rows Font Color Choose a font color for odd rows Height Specify the height, in pixels, of this control. Keep together If set to true, the contents of the control will be kept on a single page. This property is overridden to 368 MBPM Designer User's Guide Chapter 33 Introduction to Reports Property Name Description change its default value to false. Use this property to specify whether the contents of the table can be horizontally split across pages, or whether the table (all table rows) will be entirely printed on the next page. Left Select the size of the padding to the left for all rows Left Select the size of the padding to the left for even rows Left Select the size of the padding to the left for odd rows Name Specify a unique name to identify the style Name Specify a unique name to identify the style Name Specify a unique name to identify the style Name Specify a unique name to identify this control. This name is not visible at run-time. Notes Use this to enter any specific notes for anyone using this control within the Designer environment. Odd Style Select an existing style or create a new style Padding Parent property for selecting the size of padding at the left, right, top, bottom of all rows Padding Parent property for selecting the size of padding at the left, right, top, bottom of even rows Padding Parent property for selecting the size of padding at the left, right, top, MBPM Designer User's Guide 369 Chapter 33 Introduction to Reports Property Name Description bottom of odd rows Position from left The position (in pixels) of this control, from the left hand side of the process design surface Position from top The position (in pixels) of this control, from the top edge of the report area Right Select the size of the padding to the right for all rows Right Select the size of the padding to the right for even rows Right Select the size of the padding to the right for odd rows Style Select an existing style or create a new style Styles Parent property for the grid styles Text Select the alignment to be used for alignment all rows Text Select the alignment to be used for alignment even rows Text Select the alignment to be used for alignment odd rows Top Select the size of the padding to the top for all rows Top Select the size of the padding to the top for even rows Top Select the size of the padding to the top for odd rows Visible Whether or not this control should be visible. Width Specify the width, in pixels, of this control 370 MBPM Designer User's Guide Chapter 33 Introduction to Reports Grid Cell Property Name Description Border color Choose a border color for this section Border width Choose a border width for this section Borders Choose what borders should be displayed Caption Choose a caption for this control. Normally it is the caption which is visible at runtime. Color Choose a background color for this cell Font Color Choose a font color for this grid cell Height Specify the height, in pixels, of this control. Keep together If set to true, the contents of the control will be kept on a single page Name Specify a unique name to identify this control. This name is not visible at runtime. Visible Whether or not this control should be visible. Width Specify the width, in pixels, of this control Word wrap Wrap text in this control Note that you cannot bind an image directly to a grid cell. However, you can add the image control to the Grid Cell and bind the picture variable to the Image control within the Grid cell. MBPM Designer User's Guide 371 Chapter 33 Introduction to Reports Grid Row Property Name Description Border color Choose a border color for this section Border width Choose a border width for this section Borders Choose what borders should be displayed Color Choose a background color for this row Font Color Choose a font color for this grid row Height Specify the height, in pixels, of this control. Keep together If set to true, the contents of the control will be kept on a single page Name Specify a unique name to identify this control. This name is not visible at runtime. Visible Whether or not this control should be visible. Width Specify the width, in pixels, of this control Grid footer band Property Name Description Color Choose a background color for this band Font Color Choose a font color for this band Height Specify the height, in pixels, of this control. 372 MBPM Designer User's Guide Chapter 33 Introduction to Reports Property Name Description Keep together If set to true, the contents of the entire band will be kept on a single page Name Specify a unique name to identify this control. This name is not visible at runtime. Notes Use this to enter any specific notes for anyone using this control within the Designer environment. Print at bottom Specifies whether the group footer should be printed at the bottom of the page or immediately after the last group's details Repeat every page Specifies whether the group footer should be repeated on every page Visible Whether or not this control should be visible. Grid header band Property Name Description Color Choose a background color for this band Font Color Choose a font color for this band Height Specify the height, in pixels, of this control. Keep together If set to true, the contents of the entire band will be kept on a single page Name Specify a unique name to identify this control. This MBPM Designer User's Guide 373 Chapter 33 Introduction to Reports Property Name Description name is not visible at runtime. Notes Use this to enter any specific notes for anyone using this control within the Designer environment. Repeat every page Specifies whether the group header should be repeated on every page Visible Whether or not this control should be visible. Hyperlink Property Name Description Name Specify a unique name to identify this control. This name is not visible at runtime. Caption Choose a caption for this control. It is the caption which is visible at runtime. Position from left The position (in pixels) of this control, from the left hand side of the process design surface Position from top The position (in pixels) of this control, from the top edge of the report area Height Specify the height, in pixels, of this control. Width Specify the width, in pixels, of this control. Hyperlink type You can set the hyperlink type to one of the following: l 374 Dynamic MBPM Designer User's Guide Chapter 33 Introduction to Reports Property Name Description If you choose Dynamic, following additional properties are displayed: 1. TargetURL 2. Variable TargetURL: Click on the ellipsis of TargetURL.’ You can set prefix and suffix values here. You can enter static text as a prefix and point to a Business Object item as a suffix. All the variables for the Business Object bound to the Report are available under the Business Object Item drop-down. Variable: Click on the drop-down and select the variables of the Business Object associated with the Report. l Open existing folder If you choose to open an existing folder, an additional property is displayed: 1. FolderID 2. Variable FolderID: You can click in the dropdown containing the variables for the Business Object bound to the Report. This is the FolderID that will be opened by the hyperlink. Variable: Click on the drop-down and MBPM Designer User's Guide 375 Chapter 33 Introduction to Reports Property Name Description select the variables of the Business Object associated with the Report. l Open report If you choose open a report, the following additional properties are displayed: Report Group Report Name Parameters For the Report Group property, an editable dropdown is displayed. Here you can either use the drop-down to select the report groups within the project or manually type in the report group that is outside of the project. For the Report Name property, an editable dropdown is displayed. Here you can either use the drop-down to select the report names within the project or manually type in the report name that is outside of the project. For the Parameters property, you can open a dialog where the parameters and their values can be specified. Here you can select a field name of the Report identified using the Report Group and Report Name. You can also type in the name of a field as the parameter name. For every parameter name 376 MBPM Designer User's Guide Chapter 33 Introduction to Reports Property Name Description specified, you can either select a Business Object variable (from the Business Object bound to the Report) or can type in a static value. l Static If you choose Static, the following additional property is displayed: TargetURL Enter a static URL in the TargetURL property. For example: http://www.opentext.com. Keep in mind the following: l l MBPM Designer User's Guide If loading a report from a hyperlink, the report always loads with what is defined in On load property of the report regardless of what parameters have been passed from the hyperlink. An If/Else activity can be used (for On Load property of the Report which will be referenced) to confirm if report's parameters have been passed from the hyperlink. In IE7.0, an error message about hyperlink being too long is displayed if you pass too many parameters. This error does not appear when using IE8 or Firefox. 377 Chapter 33 Introduction to Reports Property Name Description Target URL This field is displayed when Static or Dynamic is chosen as the Hyperlink type. If Static is chosen, enter the URL that should be displayed in this field when Web Client user clicks on it. If Dynamic is chosen, click on the ellipsis of TargetURL. You can set prefix and suffix values here. You can enter static text as a prefix and point to a Business Object item as a suffix. All the variables for the Business Object bound to the Report are available under the Business Object Item drop-down. Font Choose a font for this control. Font Color Choose a font color from custom and Web types for this control. Visible Whether or not this control should be visible. Variable Select a Business Object variable that will be used to populate the checkbox. Keep together If set to true, the contents of the control will be kept on a single page. Format Specifies how the contents should be formatted. Summary function Selecting this option enables the following 378 MBPM Designer User's Guide Chapter 33 Introduction to Reports Property Name Description fields: Applied to: Select from Report, Group, or Page. Function: Select from a list of the available functions. Ignore Null Values: Select the option to ignore null values while computing the selected function. Notes Use this to enter any specific notes for anyone using this control within the Designer environment. Image Property Name Description Border color Choose a border color for this section Border width Choose a border width for this section Borders Choose what borders should be displayed Height Specify the height, in pixels, of this control. Name Specify a unique name to identify this control. This name is not visible at runtime. Notes Use this to enter any specific notes for anyone using this control within the Designer environment. Picture Choose a graphic for this image control Position from left The position (in pixels) of this control, from the left MBPM Designer User's Guide 379 Chapter 33 Introduction to Reports Property Name Description hand side of the process design surface Position from top The position (in pixels) of this control, from the top edge of the report area Width Specify the width, in pixels, of this control Label Property Name Description Caption Choose a caption for this control. Normally it is the caption which is visible at runtime. Font Choose a font for this control Height Specify the height, in pixels, of this control. Keep together If set to true, the contents of the control will be kept on a single page Name Specify a unique name to identify this control. This name is not visible at runtime. Notes Use this to enter any specific notes for anyone using this control within the Designer environment. Position from left The position (in pixels) of this control, from the left hand side of the process design surface Position from top The position (in pixels) of this control, from the top edge of the report area 380 MBPM Designer User's Guide Chapter 33 Introduction to Reports Property Name Description Variable select a Business Object variable that will be used to populate the checkbox Visible Whether or not this control should be visible. Width Specify the width, in pixels, of this control Memo Property Name Description Caption Choose a caption for this control. Normally it is the caption which is visible at runtime. Color Choose a background color for this control Font Color Choose a font color for this memo Height Specify the height, in pixels, of this control. Keep together If set to true, the contents of the control will be kept on a single page Lines Lists the value populating each line of the memo Name Specify a unique name to identify this control. This name is not visible at runtime. Notes Use this to enter any specific notes for anyone using this control within the Designer environment. Position from left The position (in pixels) of this control, from the left hand side of the process MBPM Designer User's Guide 381 Chapter 33 Introduction to Reports Property Name Description design surface Position from top The position (in pixels) of this control, from the top edge of the report area Variable select a Business Object variable that will be used to populate the checkbox Visible Whether or not this control should be visible. Width Specify the width, in pixels, of this control Native Report Property Name Description Bottom Select the size of the bottom margin Business Object Select the Business Object to be used for the report Color Choose a background color for this control Font Choose a font for this watermark Font Color Choose a font color Height Specify the height, in pixels, of this control. Image Select an image for the watermark Image Align Specify how the image should be aligned Image Tiling Select whether the image should be tiled Left Select the size of the left margin 382 MBPM Designer User's Guide Chapter 33 Introduction to Reports Property Name Description Margins Parent property listing the margins of the bottom, top, left, right of the report Name Specify a unique name to identify this control. This name is not visible at runtime. Notes Use this to enter any specific notes for anyone using this control within the Designer environment. Orientation Choose the orientation of the report Page height Sets the height of the printed page Page width Sets the width of the printed page Paper kind Specify the paper format that will be used for printing. Paper name Specify the name of the custom paper which is used in the printer that the document is going to be printed on Printer name Specify the name of the printer to use when printing the report Right Select the size of the right margin Size Parent property for Width and Height Text Specify the text to be displayed in the watermark Text alignment Choose the alignment (left, MBPM Designer User's Guide 383 Chapter 33 Introduction to Reports Property Name Description center, right) for the caption the user will see for this control Top Select the size of the top margin Visible Whether or not this control should be visible. Watermark Use a watermark Width Specify the width, in pixels, of this control Page break Property Name Description Name Specify a unique name to identify this control. This name is not visible at runtime. Notes Use this to enter any specific notes for anyone using this control within the Designer environment. Position from top The position (in pixels) of this control, from the top edge of the report area Page footer band Property Name Description Color Choose a background color for this control Font Color Choose a font color for this band Height Specify the height, in pixels, of this control. Keep together If set to true, the contents 384 MBPM Designer User's Guide Chapter 33 Introduction to Reports Property Name Description of the entire band will be kept on a single page Name Specify a unique name to identify this control. This name is not visible at runtime. Notes Use this to enter any specific notes for anyone using this control within the Designer environment. Visible Whether or not this control should be visible. Page header band Property Name Description Color Choose a background color for this control Font Color Choose a font color for this band Height Specify the height, in pixels, of this control. Keep together If set to true, the contents of the entire band will be kept on a single page Name Specify a unique name to identify this control. This name is not visible at runtime. Notes Use this to enter any specific notes for anyone using this control within the Designer environment. Visible Whether or not this control should be visible. MBPM Designer User's Guide 385 Chapter 33 Introduction to Reports Page Info Property Name Description Alignment Choose the alignment (left, center, right) for the caption the user will see for this control Color Choose a background color for this control Format Apply a format to the result (eg dd/mmm/yy, and so on) Height Specify the height, in pixels, of this control. Name Specify a unique name to identify this control. This name is not visible at runtime. Notes Use this to enter any specific notes for anyone using this control within the Designer environment. Page Information Specify what page information must be displayed Position from left The position (in pixels) of this control, from the left hand side of the process design surface Position from top The position (in pixels) of this control, from the top edge of the report area Start Page Number Defines the number to be used as the starting number Visible Whether or not this control should be visible. Width Specify the width, in pixels, of this control 386 MBPM Designer User's Guide Chapter 33 Introduction to Reports Panel Property Name Description Color Choose a background color for this control Height Specify the height, in pixels, of this control. Keep together If set to true, the contents of the control will be kept on a single page Name Specify a unique name to identify this control. This name is not visible at runtime. Notes Use this to enter any specific notes for anyone using this control within the Designer environment. Position from left The position (in pixels) of this control, from the left hand side of the process design surface Position from top The position (in pixels) of this control, from the top edge of the report area Visible Whether or not this control should be visible. Width Specify the width, in pixels, of this control Report Filter Area Property Name Description Caption Choose a caption for this control. Normally it is the caption which is visible at runtime. Client extensions The field is included only MBPM Designer User's Guide 387 Chapter 33 Introduction to Reports Property Name Description for backwards compatibility. Color Choose a background color for this report filter area Description Enter a description for this control Font Choose a font for this control Font Color Choose a font color for this filter area Height Specify the height, in pixels, of this control. Name Specify a unique name to identify this control. This name is not visible at runtime. Notes Use this to enter any specific notes for anyone using this control within the Designer environment. On cancel Do this when the filter is cancelled On load Do this when the report loads On submission Do this when the filter is submitted Restrict viewing to ... Specify the roles that can view this report. When user exits filter Use this field to enter a visual script that is run when the user exits the filter When user loads filter Use this field to enter a visual script that is run when the filter is loaded 388 MBPM Designer User's Guide Chapter 33 Introduction to Reports Property Name Description Width Specify the width, in pixels, of this control Report footer band Property Name Description Color Choose a background color for this band Font Color Choose a font color for this band Height Specify the height, in pixels, of this control. Keep together If set to true, the contents of the entire band will be kept on a single page Name Specify a unique name to identify this control. This name is not visible at runtime. Notes Use this to enter any specific notes for anyone using this control within the Designer environment. Visible Whether or not this control should be visible. Report header band Property Name Description Color Choose a background color for this band Font Color Choose a font color for this band Height Specify the height, in pixels, of this control. Keep together If set to true, the contents MBPM Designer User's Guide 389 Chapter 33 Introduction to Reports Property Name Description of the entire band will be kept on a single page Name Specify a unique name to identify this control. This name is not visible at runtime. Notes Use this to enter any specific notes for anyone using this control within the Designer environment. Page break Returns a value that determines where to make a page break, in respect to the given band. Visible Whether or not this control should be visible. Shape Property Name Description Angle Defines the angle of the shape Color Choose a background color for this control Fill color Choose a fill color for this shape Height Specify the height, in pixels, of this control. Line Color Foreground color of control Line width Width of the shape's border Name Specify a unique name to identify this control. This name is not visible at runtime. Notes Use this to enter any 390 MBPM Designer User's Guide Chapter 33 Introduction to Reports Property Name Description specific notes for anyone using this control within the Designer environment. Position from left The position (in pixels) of this control, from the left hand side of the process design surface Position from top The position (in pixels) of this control, from the top edge of the report area Shape type Specify the shape type Stretch Defines whether the shape should stretch when a rotation is applied Visible Whether or not this control should be visible. Width Specify the width, in pixels, of this control Top margin band Property Name Description Color Choose a background color for this control Font Color Choose a font color for this band Height Specify the height, in pixels, of this control. Keep together If set to true, the contents of the entire band will be kept on a single page Name Specify a unique name to identify this control. This name is not visible at runtime. Notes Use this to enter any MBPM Designer User's Guide 391 Chapter 33 Introduction to Reports Property Name Description specific notes for anyone using this control within the Designer environment. Visible Whether or not this control should be visible. Filter Controls The Filter controls of the Report Filter toolbox functions the same way as Form controls of the Form Toolbox. Filter controls and their properties The following tables list all the filter controls and their properties. Checkbox Property Name Description Business Object Item Select a Business Object variable as the Parameter value Calculation Specify a calculation to retrieve the parameter value. Caption Choose a caption for this control. Normally it is the caption which is visible at runtime. Caption alignment Choose the alignment (left, center, right) for the caption the user will see for this control Client extensions The field is included only for backwards compatibility. Default action behavior Specify a default action usage status for this control. Field has dependants of its Check this to indicate that 392 MBPM Designer User's Guide Chapter 33 Introduction to Reports Property Name Description own other field(s) on this form are dependent on this field, and it should therefore be updated when any field marked 'field is dependent on another' is changed Field is dependent on another Check this if you want this field to be updated when any field marked 'field has dependents of its own' has been changed Hint Type in the text you want to use to explain to a user how to use this control. Hint text appears when the use rolls or hovers over the control. Name Specify a unique name to identify this control. This name is not visible at runtime. Notes Use this to enter any specific notes for anyone using this control within the Designer environment. On field entry Do this when the control acquires system focus On field exit Do this when system focus moves away Position from left The position (in pixels) of this control, from the left hand side of the report. Position from top The position (in pixels) of this control, from the top edge of the report area Variable select a Business Object variable that will be used MBPM Designer User's Guide 393 Chapter 33 Introduction to Reports Property Name Description to populate the checkbox Visibility depends on Indicates rules for showing the control When changed Use this to create a visual script which is run when this control has been changed Width Specify the width, in pixels, of this control Command button Property Name Description Action name Once you've chosen a process, choose the action to run in that process. Button action Choose the type of operation this button will perform when pressed Caption Choose a caption for this control. Normally it is the caption which is visible at runtime. Client extensions The field is included only for backwards compatibility. Default action be ha vi our Specify a default action usage status for this control. Height Specify the height, in pixels, of this control. Hint Type in the text you want to use to explain to a user how to use this control. Hint text appears when the use rolls or hovers over the control. 394 MBPM Designer User's Guide Chapter 33 Introduction to Reports Property Name Description Name Specify a unique name to identify this control. This name is not visible at runtime. Notes Use this to enter any specific notes for anyone using this control within the Designer environment. Open folder (Folder ID) Choose a specific folder to open when this button is pressed. You can also enter an expression to dynamically choose a particular folder at runtime. Position from left The position (in pixels) of this control, from the left hand side of the report. Position from top The position (in pixels) of this control, from the top edge of the report area Process name Choose a process which has an action you want to run, when this button is pressed. Visibility depends on Indicates rules for showing the control When button pressed Use this field to enter a visual script that is run when the button is pressed When button pressed Do this when the button is clicked Width Specify the width, in pixels, of this control MBPM Designer User's Guide 395 Chapter 33 Introduction to Reports Date/Time Property Name Description Business Object Item select a Business Object variable as the Parameter value Calculation Specify a calculation to retrieve the parameter value. Caption Choose a caption for this control. Normally it is the caption which is visible at runtime. Caption alignment Choose the alignment (left, center, right) for the caption the user will see for this control Client extensions The field is included only for backwards compatibility. Default action be ha vi our Specify a default action usage status for this control. Disable timezone adjustment Choose whether or not to disable time zone adjustment for this control Earliest Use this to define the earliest value that can be entered in this field. Field has dependants of its own Check this to indicate that other field(s) on this form are dependent on this field, and it should therefore be updated when any field marked 'field is dependent on another' is changed Field is dependent on another Check this if you want this field to be updated when 396 MBPM Designer User's Guide Chapter 33 Introduction to Reports Property Name Description any field marked 'field has dependents of its own' has been changed Format Choose whether this field should display a date, a time, or both. Hint Type in the text you want to use to explain to a user how to use this control. Hint text appears when the use rolls or hovers over the control. Latest Choose the latest date and/or time which can be shown in this control Name Specify a unique name to identify this control. This name is not visible at runtime. Notes Use this to enter any specific notes for anyone using this control within the Designer environment. On field entry Do this when the control acquires system focus On field exit Do this when system focus moves away Position from left The position (in pixels) of this control, from the left hand side of the report. Position from top The position (in pixels) of this control, from the top edge of the report area Variable select a Business Object variable that will be used to populate the checkbox Visibility depends on Indicates rules for showing MBPM Designer User's Guide 397 Chapter 33 Introduction to Reports Property Name Description the control When changed Use this to create a visual script which is run when this control has been changed Width Specify the width, in pixels, of this control Dropdown Property Name Description Business Object Item select a Business Object variable as the Parameter value Calculation Specify a calculation to retrieve the parameter value. Caption Choose a caption for this control. Normally it is the caption which is visible at runtime. Caption alignment Choose the alignment (left, center, right) for the caption the user will see for this control Client extensions The field is included only for backwards compatibility. Default action be ha vi our Specify a default action usage status for this control. Field has dependants of its own Check this to indicate that other field(s) on this form are dependent on this field, and it should therefore be updated when any field marked 'field is dependent on another' is 398 MBPM Designer User's Guide Chapter 33 Introduction to Reports Property Name Description changed Field is dependent on another Check this if you want this field to be updated when any field marked 'field has dependents of its own' has been changed Hint Type in the text you want to use to explain to a user how to use this control. Hint text appears when the use rolls or hovers over the control. List options Click here to define the options which appear in this list Name Specify a unique name to identify this control. This name is not visible at runtime. Notes Use this to enter any specific notes for anyone using this control within the Designer environment. On field entry Do this when the control acquires system focus On field exit Do this when system focus moves away Position from left The position (in pixels) of this control, from the left hand side of the report. Position from top The position (in pixels) of this control, from the top edge of the report area Variable select a Business Object variable that will be used to populate the checkbox Visibility depends on Indicates rules for showing MBPM Designer User's Guide 399 Chapter 33 Introduction to Reports Property Name Description the control When changed Use this to create a visual script which is run when this control has been changed Width Specify the width, in pixels, of this control Image Property Name Description Client extensions The field is included only for backwards compatibility. Height Specify the height, in pixels, of this control. Name Specify a unique name to identify this control. This name is not visible at runtime. Notes Use this to enter any specific notes for anyone using this control within the Designer environment. Picture Choose a graphic for this image control Position from left The position (in pixels) of this control, from the left hand side of the report. Position from top The position (in pixels) of this control, from the top edge of the report area URL URL Visibility depends on Indicates rules for showing the control Width Specify the width, in pixels, of this control 400 MBPM Designer User's Guide Chapter 33 Introduction to Reports Label Property Name Description Caption alignment Choose the position for the caption of this field above, below, to the left or to the right Client extensions The field is included only for backwards compatibility. Font Choose a font for this control Height Specify the height, in pixels, of this control. Name Specify a unique name to identify this control. This name is not visible at runtime. Notes Use this to enter any specific notes for anyone using this control within the Designer environment. Position from left The position (in pixels) of this control, from the left hand side of the report. Position from top The position (in pixels) of this control, from the top edge of the report area URL URL to link to Visibility depends on Indicates rules for showing the control Width Specify the width, in pixels, of this control MBPM Designer User's Guide 401 Chapter 33 Introduction to Reports Memo Property Name Description Business Object Item select a Business Object variable as the Parameter value Calculation Specify a calculation to retrieve the parameter value. Caption Choose a caption for this control. Normally it is the caption which is visible at runtime. Caption alignment Choose the position for the caption of this field above, below, to the left or to the right Client extensions The field is included only for backwards compatibility. Default action be ha vi our Specify a default action usage status for this control. Field has dependants of its own Check this to indicate that other field(s) on this form are dependent on this field, and it should therefore be updated when any field marked 'field is dependent on another' is changed Field is dependent on another Check this if you want this field to be updated when any field marked 'field has dependents of its own' has been changed Height Specify the height, in pixels, of this control. Hint Type in the text you want 402 MBPM Designer User's Guide Chapter 33 Introduction to Reports Property Name Description to use to explain to a user how to use this control. Hint text appears when the use rolls or hovers over the control. Name Specify a unique name to identify this control. This name is not visible at runtime. Notes Use this to enter any specific notes for anyone using this control within the Designer environment. On field entry Do this when the control acquires system focus On field exit Do this when system focus moves away Position from left The position (in pixels) of this control, from the left hand side of the report. Position from top The position (in pixels) of this control, from the top edge of the report area Variable select a Business Object variable that will be used to populate the checkbox Visibility depends on Indicates rules for showing the control When changed Use this to create a visual script which is run when this control has been changed Width Specify the width, in pixels, of this control MBPM Designer User's Guide 403 Chapter 33 Introduction to Reports Number Property Name Description Business Object Item select a Business Object variable as the Parameter value Calculation Specify a calculation to retrieve the parameter value. Caption Choose a caption for this control. Normally it is the caption which is visible at runtime. Caption alignment Choose the position for the caption of this field above, below, to the left or to the right Client extensions The field is included only for backwards compatibility. Decimal places Specify the number of decimal places which will be shown in this field. Default action behavior Specify a default action usage status for this control. Field has dependants of its own Check this to indicate that other field(s) on this form are dependent on this field, and it should therefore be updated when any field marked 'field is dependent on another' is changed Field is dependent on another Check this if you want this field to be updated when any field marked 'field has dependents of its own' has been changed 404 MBPM Designer User's Guide Chapter 33 Introduction to Reports Property Name Description Hint Type in the text you want to use to explain to a user how to use this control. Hint text appears when the use rolls or hovers over the control. Maximum enabled Indicate whether or not you want to set a maximum value for this field. Maximum value Choose a maximum value that this field may have. Minimum enabled Indicate whether or not you want to set a minimum value for this field. Minimum value Choose a minimum value that this field may have. Name Specify a unique name to identify this control. This name is not visible at runtime. Notes Use this to enter any specific notes for anyone using this control within the Designer environment. On field entry Do this when the control acquires system focus On field exit Do this when system focus moves away Position from left The position (in pixels) of this control, from the left hand side of the report. Position from top The position (in pixels) of this control, from the top edge of the report area Variable select a Business Object variable that will be used MBPM Designer User's Guide 405 Chapter 33 Introduction to Reports Property Name Description to populate the checkbox Visibility depends on Indicates rules for showing the control When changed Use this to create a visual script which is run when this control has been changed Width Specify the width, in pixels, of this control Rule Property Name Description Client extensions The field is included only for backwards compatibility. Color Choose a color for this line or box Height Specify the height, in pixels, of this control. Name Specify a unique name to identify this control. This name is not visible at runtime. Notes Use this to enter any specific notes for anyone using this control within the Designer environment. Position from left The position (in pixels) of this control, from the left hand side of the report. Position from top The position (in pixels) of this control, from the top edge of the report area Style Style for the rule 406 MBPM Designer User's Guide Chapter 33 Introduction to Reports Property Name Description Type Rule type Visibility depends on Indicates rules for showing the control Width Specify the width, in pixels, of this control Text Property Name Description Business Object Item select a Business Object variable as the Parameter value Calculation Specify a calculation to retrieve the parameter value. Caption Choose a caption for this control. Normally it is the caption which is visible at runtime. Caption alignment Choose the position for the caption of this field above, below, to the left or to the right Client extensions The field is included only for backwards compatibility. Default action behavior Specify a default action usage status for this control. Field Alignment Choose an alignment (left, center or right) for this control Field has dependants of its own Check this to indicate that other field(s) on this form are dependent on this field, and it should therefore be updated when MBPM Designer User's Guide 407 Chapter 33 Introduction to Reports Property Name Description any field marked 'field is dependent on another' is changed Field is dependent on another Check this if you want this field to be updated when any field marked 'field has dependents of its own' has been changed Hint Type in the text you want to use to explain to a user how to use this control. Hint text appears when the use rolls or hovers over the control. Mask Mask to use for text entry Maximum length Indicate the maximum length (in number of characters) for this field. Name Specify a unique name to identify this control. This name is not visible at runtime. Notes Use this to enter any specific notes for anyone using this control within the Designer environment. On field entry Do this when the control acquires system focus On field exit Do this when system focus moves away Password Defines that the field will contain a password. Position from left The position (in pixels) of this control, from the left hand side of the report. Position from top The position (in pixels) of this control, from the top 408 MBPM Designer User's Guide Chapter 33 Introduction to Reports Property Name Description edge of the report area Variable select a Business Object variable that will be used to populate the checkbox Visibility depends on Indicates rules for showing the control When changed Use this to create a visual script which is run when this control has been changed Width Specify the width, in pixels, of this control Custom Lists A custom list is used in the Designer to display a grid containing a number of columns in the MBPM Web Client. In the MBPM Web Client, a custom list can have filters for the data in its columns allowing the user to filter the list of data displayed in the grid by selecting from one or more dropdowns. Creating a Custom List To create a Custom List: 1. In the MBPM Designer, click the Home ribbon tab. 2. In the Components group of the Home ribbon tab, click CustomList component. Associating a Business Object with Custom List To associate a Business Object with Custom List: 1. Go to Toolbox in the Designer. 2. Scroll down to Business Objects section. 3. Drag the Business Object that you would like to associate with the Custom List and drop it in the main pane of the Designer displaying the Custom List. A new Business Object is created in the "Other Business Objects" section of Data Access. 4. In the Properties pane of the Custom List, click the Business Object drop-down list and choose the newly created Business Object instance created. The Business Object is now associated with the Custom List. MBPM Designer User's Guide 409 Chapter 33 Introduction to Reports Creating columns for the Custom List To create columns in the Custom List: 1. Go to Data Access. 2. Drag the variables displayed under the Business Object created in the "Other Business Objects" and drop them in the Custom List control. Note: Status fields can be used as columns in Custom lists. (Processes are deployed using non GIF images for standard image types in the Designer. This is because GIF image format is not supported in the MBPM Smart Business Workspace). 3. Alternatively, in the Custom List's Columns properties, click ellipses. A pop-up window is displayed where you can create columns. 4. Click Add and Delete buttons to add or delete columns. 5. To set the properties of a column, use the properties in the right-pane of the pop-up window. Only properties relevant to the column type are displayed. Column Property Description Name Set the name of the column. Caption Set a caption that will be displayed in the Web Client when deployed. Type Set the data type of the control. You can choose from Text, Currency, Date Time , Number, Folder, Hyperlink or Person depending on the column type being created. The following table describes the available data types. Data Type Property Description Text Field Alignment Choose between Left, Center, and Right. Maximum Length This property is displayed for a Text type. Default value is 250. 410 MBPM Designer User's Guide Chapter 33 Introduction to Reports Data Type Property Description Currency Currency symbol Enter the type of decimal value. Symbol Position Choose from Before umber or After number. Negative Number Style Choose from Before number, After number, and Parenthesis. Decimal Places Default value is 0. You can set to positive or negative number. Date Time Format Choose from Date, Time or Both. Number Decimal Places Default value is 0. You can set to positive or negative number. Folder Field Alignment Choose between Left, Center, and Right. Display text Defaults to Open folder that can be changed. Display value You can choose a Business Object variable. The items of the Business Objects associated with the Custom list are available here. Hyperlink MBPM Designer User's Guide 411 412 MBPM Designer User's Guide Chapter 34 Using Charts in Reports Chapter 34 Using Charts in Reports You can add a chart to a report by dragging and dropping the Chart report control in the Report Area of a Report. Adding a chart control displays the Chart Design context ribbon. Chart Design Context Ribbon The Chart Design context ribbon is displayed only when a chart is active. Chart Composition The following items identify the composition of charts. 1. Chart Title 2. Labels 3. Major Grid Lines 4. Minor Grid Lines 5. Markers 6. Legend 7. Y-axis 8. X-axis These are represented below. You can select these items within a chart and modify their properties. MBPM Designer User's Guide 413 Chapter 34 Using Charts in Reports Setting Chart Appearance You can modify a chart's appearance using several settings as mentioned in this topic. Series You can use the Add and Remove buttons to add or remove a series from a chart. You can also click on the dialog box launcher in the Series group to display the Series Collection Editor to add or remove series. Arrange Series You can re-arrange the series using the Move Up and Move Down buttons. 414 MBPM Designer User's Guide Chapter 34 Using Charts in Reports Type The Type group allows you to choose a format for your chart. Styles The Styles group in the Chart Design Context ribbon has two options: l Palette l Variation Palette The Palette drop-down menu provides a set of default palettes to select from. You may also create a custom appearance palette and add it to the menu. To set the appearance of a chart, click on Palette and select a palette from the drop-down menu. Define Custom Palettes 1. On the Styles group, click on the dialog box launcher . The Palettes Editor is displayed. 2. Click on the right Add button. A new palette is added to the list in the left pane and a grey color bar (Double-click to edit) is added to the right pane. 3. With the new palette selected, in the right pane, double click on the grey bar to display a color palette. 4. Change the grey color in the color palette. 5. To add more color bars to the right pane, click on the right Add button and edit as required. 6. Click the OK button to save your changes. The new palette is added to the Chart Appearance drop down menu. Editing Default Palettes You cannot edit the default palettes but you can copy a default palette and then edit the copy. 1. In the left pane, select a default palette. 2. Click on the Copy button. A new palette with the same theme is added to the list. 3. Select the copied palette and edit the colors in the right pane. 4. Click OK to save the new palette. MBPM Designer User's Guide 415 Chapter 34 Using Charts in Reports Variations The Variations drop-down menu provides a set of default styles to select from based on the palette chosen in Chart Appearance. To set the chart style: l Click on Variations and select a style from the drop-down menu. l Certain styles may override some of the chart palette settings. The following example displays a Pie 3D chart and the effects of applying two different palettes to the default palette and then a dark flat yellow style. l The style colors override the appearance colors. 416 MBPM Designer User's Guide Chapter 34 Using Charts in Reports Elements Chart title Click Chart title to toggle the display of a chart title. Legend Choose the appropriate position to display the legend of a chart. The options are Top, Bottom, Left, and Right. You can also choose to hide the legend display. Point Options Arguments are displayed on the X-axis and values are represented on Y-axis. Argument You can choose to display the chart's arguments instead of values by clicking this option. Values You can choose to display or hide the chart's values instead of arguments by clicking this option. Labels You can choose to display or hide the labels. Markers If you choose a Point and Line chart type, you can click Markers to choose from squares, triangles, and so on to display the series. Axes Grid Lines X-axis You can choose to display or hide all grid lines of X-axis, only its major grid lines or none. Y-axis You can choose to display or hide all grid lines of Y-axis, only its major grid lines or none. Axes X-axis You can choose to display or hide the X-axis and its orientation in standard axis direction or reverse axis direction. Y-axis You can choose to display or hide the Y-axis and its orientation in standard axis direction or reverse axis direction. Labels MBPM Designer User's Guide 417 Chapter 34 Using Charts in Reports You can choose labels to be displayed in staggered or straight orientation. Selecting Chart Types To set the type of chart displayed. 1. On the Chart Design context ribbon, in the Type group, click on a drop-down button (for example Pie). 2. Select a chart option from the sub-menu. The available chart type options are: Bars Chart Type Example Bar Bar 3D Bar Stacked 418 MBPM Designer User's Guide Chapter 34 Using Charts in Reports Points and Lines Chart Type Example Point Line Line 3D MBPM Designer User's Guide 419 Chapter 34 Using Charts in Reports Pie Chart Type Example Pie Pie 3D Areas Chart Type Example Area Area Stacked 420 MBPM Designer User's Guide Chapter 34 Using Charts in Reports Note: During run-time, if the chart does not display the data correctly, resize (increase the size) the chart in the Designer. Chart controls and their properties The following tables list all the chart controls and their properties. Chart Property Name Description Border color Choose a border color for this section. Border width Choose a border width for this section. Borders Choose what borders should be displayed. Chart Title Specify whether to display the title. Height Specify the height, in pixels, of this control. Left Position from left. Name Specify a unique name to identify this control. This name is not visible at runtime. Notes Use this to enter any specific notes for anyone using this control within the Designer environment. Series Display a dialog to manage the series. Title The title used for the chart. Top Position from top. Visible Whether or not this control should be visible. Width Control width. MBPM Designer User's Guide 421 Chapter 34 Using Charts in Reports Chart Axis Property Name Description Auto Range Select whether the min and max of the axis should be calculated automatically or specified manually. Label angle Sets the angle of the axis labels. Max Specify the maximum value for this axis. Min Specify the minimum value for this axis. Show Axis Title Show or hide the title for this axis. Title Choose a title for the axis. Chart Pane Property Name Description Border color Choose a border color for this section. BorderVisible Toggles whether the border for the chart pane is visible or hidden. Color Choose a background color for this chart pane. Name Specify a unique name to identify this control. This name is not visible at runtime. Pane Parent property for the pane properties. Rotated Rotate. 422 MBPM Designer User's Guide Chapter 34 Using Charts in Reports Chart Series Property Name Description Name Specify a unique name to identify this control. This name is not visible at runtime. Scale Type Scale Type defines the underlying data source type of the Y axis in order for the chart to interpret how to display the data. Note that when the Scale Type property is changed from Qualitative to Numeric, the Auto Range property for the Chart axis (X-axis or Y-axis) needs to be re-enabled. X Values The data source used to define the values (x data) of the series. Y Data The data source used to define the data (y-data) of the series. Use Top N Select whether it is required to display only Top N series points in a series. Count Specify the total number of Top N series points. Format Sets the format for the data displayed on the chart. Currency: Currency Symbol: Enter the type of currency symbol that should be displayed. MBPM Designer User's Guide 423 Chapter 34 Using Charts in Reports Property Name Description Currency Symbol Position: Set the currency symbol to be displayed before or after the number (data). Fixed Point: Data is displayed as real numbers with fractional part. General: Data is displayed in a generic text format. Number: Integer part of data is displayed. Percent: Data is displayed as a percentage. Scientific: Data is displayed in scientific notation. For example, 9.70E+000 Precision Indicates the desired number of decimal places. Notes Use this to enter any specific notes for anyone using this control within the Designer environment. Chart Series (Common) Property Name Description Function Applies a function to be calculated against a specified variable. Name Specify a unique name to identify this control. This name is not visible at runtime. Notes Use this to enter any specific notes for anyone using this control within the Designer environment. Scale Type Scale Type defines the underlying data source type of the Y axis in order for the chart to interpret how to display the data. Note that when the Scale Type property is changed from Qualitative to Numeric, the Auto Range property for the Chart axis (X-axis or Yaxis) needs to be re-enabled. 424 MBPM Designer User's Guide Chapter 34 Using Charts in Reports Property Name Description Summary Function Select whether a summary function must be applied a specified variable. X Values The data source used to define the values (x data) of the series. Y Data The data source used to define the data (y-data) of the series. Chart Series (Pie Chart) Property Name Description Explode Pie Chart Explodes the slices of the pie. Show as Percentage Display the series values as percentages. Chart Series (XY Chart) Property Name Description Count Specify the total number of Top N series points. Use other values as a single series Select whether all series points not included in the "Top N" must united into a single "Others" point. Use Top N Select whether it is required to display only Top N series points in a series. Diagram (XY 3D) Property Name Description Perspective Angle Specify the perspective angle for the chart. Rotation X Specify the angle at which the x axis is rotated. Rotation Y Specify the angle at which the y axis is rotated. Rotation Z Specify the angle at which the z axis is rotated. Show X Axis Title Show or hide the title for this axis. Show Y Axis Title Show or hide the title for this axis. Text Choose a title for the axis. X Axis Label angle Sets the angle of the axis labels. Y Axis Label angle Sets the angle of the axis labels. MBPM Designer User's Guide 425 426 MBPM Designer User's Guide Chapter 35 Introduction to Multi-Lingual Processes Chapter 35 Introduction to Multi-Lingual Processes Multi-Lingual Processes, also called localization, enables the BPM client to display forms and processes in different languages. The Designer does not carry out any language translations itself. In fact the Designer does not actually recognize different languages. The language used to create the base process is called the 'Neutral' language. Multi-Lingual Processes allows you to create a number of language settings at project level. You can then enter translations for the forms and processes within the project. Once this has been done, you can switch between these available settings to display, for example a form, in different languages. Note: Reports will not be affected by multiple language definitions except for the report’s filter area. Users will have to design a separate report for each language used in the BPM project to display reports in different languages. The position of controls on forms can also be varied for different language settings. For example, the controls on a form could read left to right on the English version and right to left on the Arabic version. In the example below, the controls in the German version have been moved further right to allow more space for the captions. MBPM Designer User's Guide 427 Chapter 35 Introduction to Multi-Lingual Processes In the above example, the following are represented: 1. Set the available languages in the project. 2. Enter the translations in the Translations pane. 428 MBPM Designer User's Guide Chapter 35 Introduction to Multi-Lingual Processes 3. Users can view the form in different languages. Setting the Project Languages When a project is created it is language neutral. To display project components in a different language, you must first set up the available languages in the project. l To display the project languages settings, either: n In the Inventory, double click on the Project button. n In the main pane of the Designer, select the Project tab (if available). The Project tab displays the language settings available to the project. l l l l In the left pane, select a language. Click on the add arrow button to add the language to the project. The selected languages are displayed in the right pane. Repeat steps 2 and 3 for each language to be available in the project. Click the MBPM button > Save. The language changes will not take effect until you have saved them. To remove a language from the project, in the right pane select the language and click the remove arrow button. Warning - Removing a language from the project list will remove all translations for this language, as well as all forms specific to the language that has been removed. If the project has translated items for a language, a message asking for confirmation before removing the language is displayed. Note: A project cannot be deployed in more than one language at the same time. Either the project is deployed in “language X” or in “language Y” it cannot be deployed in both. Creating the Translations The language translation of properties must be entered manually by the process Designer. Translations can be entered via: l The Translations pane l The Properties pane You cannot translate all the properties of a component. Properties seen by the user, such as Captions, Hints, Radio Group options can be translated. Properties seen by the code, such as Name or Client Extension cannot be translated. The Inventory lists the language variations of all processes and forms. This is accomplished by listing the languages for which a translation exists, within the Inventory. So, if a form has three chosen translations for English, Serbian, and Japanese, its Inventory entry will read “Form1 [EN, SE, JP]” MBPM Designer User's Guide 429 Chapter 35 Introduction to Multi-Lingual Processes In the above example: l Form1 has French and German versions. l Form 2 has a French version. Translate via the Translation Pane To translate using the Translation pane: 1. Set the Available Languages in the Project tab. 2. Select the View ribbon tab and click on the Translations button . The Translations pane is displayed with a column for each language variation set in the project, plus the neutral language. Initially, all properties are displayed in the neutral language. Any translations required must be entered in the respective columns. Note: Only the properties that can be changed are displayed. 3. In the relevant language column, click in the property field to be translated and enter the translation. For example, to display the process caption 'Process 1' in German in the German column, Project.Process.Caption field, enter 'Karte1'. 4. Repeat the above process for each property to be translated. 5. Click the MBPM button > Save. Translate via the Properties Pane To translate using the Properties pane: 1. Set the Available Languages in the Project tab. 2. In the Design pane, select the component to be translated and ensure that the Properties pane is displayed. 3. On the Status bar, in the Language variation field, select the language to be translated to from the drop-down list. 4. Click in the property field to be translated and enter the translation. For example, with the German language variation selected, click in the process Caption field and change 'Process 1' to 'Karte1'. Note: The Help URL property of actions and stages is an expression that cannot be localized. 430 MBPM Designer User's Guide Chapter 35 Introduction to Multi-Lingual Processes Designing Localization Layouts The 'default' language variation for a project is Neutral. This is the language in which the base processes, forms must be created and initially designed. The following rules apply to designing for different languages: l You can only create or delete a process or form in the neutral language. l You can only add or delete stages, actions and controls in the neutral form. l l In each language, the controls on forms initially inherit the positions set in the neutral form. These controls can then be positioned differently for each language. Removing a language from the project list removes all the translations for that language, as well as all processes and forms specific to that language. A warning message asking for confirmation is displayed before the language is removed. l The data in a form field is the same in all the language variations. l You can add and delete languages and reposition controls at any time. Repositioning Controls on Forms The controls on forms can be placed in different positions for every language variations. 1. Set up the Project language variations. 2. In the neutral language, create the form and add the controls. 3. On the Status bar, in the Language variation field, select the language required. 4. On the form, you can now: n Move the controls to new positions. n Re-size controls. n Reposition the control captions (for example, to the right instead of left). The changes are only applied to this specific language variation. In the following example, Form1 exists in both English and Arabic versions. These can be selected from the Language variations menu. MBPM Designer User's Guide 431 Chapter 35 Introduction to Multi-Lingual Processes 432 MBPM Designer User's Guide Chapter 36 Introduction to Solution Tables Chapter 36 Introduction to Solution Tables The Solution Tables feature lets you create supplementary tables from within the Designer. This eliminates the need to use database administration tools to create these tables externally on each machine running a specific project. Solution Tables created in the Designer are stored as part of the repository. You can use Solution Tables to simplify project creation. For example, if you want to populate a drop-down list with pick items, you can create the item list in a Solution Table rather than typing a list of items into the form element’s property field. Create a Solution Table To create a new solution table: 1. In the Home ribbon tab, Components group, click on the Solution Table. A new Solution Table is displayed in a tab in the main pane of the Designer with a new row selected. 2. Enter the details for the columns you want in your table. 3. In Solution table description field, enter a description for the solution table. 4. Click in the Name field and enter a name for the column. 5. Click in the Type of a column and select a data type from the drop-down list. 6. In the Description field, enter a description of the column. 7. If the table is to be indexed by this column, in the Index field, select the check box. You can index the table by multiple columns by selecting the Key check box for each column. You cannot index Check and Memo type columns. 8. In the Primary Key field, if you want to specify the column as a Primary key, select the check box. Note: You cannot set Check and Memo type columns as Primary Key. 9. If a text column has been selected, in the Size field, enter the size of the column. The maximum value is 250. You can change the name of the Solution Table by clicking on the name in the Inventory pane and entering a new name. button. In the Grid 10. To add another row to the table, click in the blank row or on the tab, use the Insert Above, Insert Below, Move Up, Move Down, and Delete buttons to MBPM Designer User's Guide 433 Chapter 36 Introduction to Solution Tables perform operations on the rows. Note: A new row with the original primary key cell value cannot be created in the same transaction. For example, create a solution table with primary key column and an editable grid that points to this solution table. At run-time, open the form containing the grid, enter a value in the primary key cell, and Submit the form. When you re-open this form, you cannot change the original primary key cell value (for example, 1) to a different value (for example, 12) and add a new row with the original primary key cell value of 1 in the same transaction as it violates the database constraint. Note: Solution Tables can be added to a Library. Identity Columns The Identity property allows you to specify columns for a Solution Table that contains autogenerated unique values. This avoids having to maintain this within the external table in the database. The property is made optional by means of a check box. The default value is off. It is only enabled for Integer fields. Only one identity column is allowed in a table. If the database is SQL Server, both the “Primary Key”, and “Index” properties can also be enabled. Solution Tables that have been loaded with version 7.6 and version 9.0 – 9.0.3 Solutions will have the Identity property enabled for Integer columns. 434 MBPM Designer User's Guide Chapter 37 Deploying a Project, Library or Solution Chapter 37 Deploying a Project, Library or Solution To deploy a Solution: 1. Click the Deploy button. To deploy a Project or Library in a Solution, click the drop-down button of the Deploy button to display a list of existing Projects or Libraries. Select the Project or Library that you want to deploy. You will be prompted to save the overall solution before you can deploy any part of it. Until you have saved the solution, you will not be able to execute either a validation or a deployment. When you have saved your project, it is automatically validated, and if validation is successful, you will be prompted to enter the user name and password for the repository to which you are deploying. Note: The component you have deployed may have previously passed validation. Even so, validation is re-run as part of deployment, since this includes a number of rules which can only be checked once you have chosen a repository to which to deploy. 2. Enter your login details. Select Remember these details if you would like MBPM to save your login details, and click OK. 3. You can now enter a description for this version of your project. 4. Type a description and click OK. Descriptions can be useful when you're navigating around multiple versions of a project in a repository. Deployment is immediate, and you can log in to see the project. MBPM Designer User's Guide 435 436 MBPM Designer User's Guide Chapter 38 Debugging Chapter 38 Debugging MBPM Designer Process Debugging feature enables you to identify and correct problems in your MBPM processes and forms. Microsoft Visual Studio debugging tool is used to handle MBPM process debugging. The Debug button is available on the Home tab besides the Deploy button only if Visual Studio is installed. For more information on Visual Studio editions required to be installed for this feature to work, see Supported Environments. Debugging a process To debug a project, click the Debug button. Visual Studio will connect to the MBPM Engine and open the generated code files. During this process, messages are displayed in the Designer Message pane. The project is deployed and C# files are generated. For location of the generated C# files, see Location of files. Visual Studio is opened and the C# files are opened as separate tabs in Visual Studio. Debugging without administrative privileges In order to debug a process on Windows Vista, Windows Server 2008 or Windows 7 without the need to turn off the UAC prompts or running the Designer with administrator privileges, the Engine must be re-configured and launched as a standard process within the user’s session rather than as a service. The following steps detail this process: 1. Install Visual Studio 2010. 2. Start Visual Studio to complete any initial environment setup. 3. Install Designer, Deployment Service, and Engine on the local machine - set the service startup type to Manual. 4. Run the Component Services tool (dcomcnfg.exe). 5. Navigate the tree to Component Services\My Computer\COM+ Applications\Metastorm Process Engine 6. Right-click Metastorm Process Engine and select Properties. MBPM Designer User's Guide 437 Chapter 38 Debugging 7. On the Identity tab, select System Account: Interactive User. 8. On the Advanced tab, select “Enable idle shutdown” and set the minutes to zero (0). 9. Press OK. 10. If the user performing the debugging is different to the user who installed BPM, then the account will need to be added to the Administrator and Client Roles by following these steps: a. Drill-down to "Roles\Administrator\Users" of "\My Computer\COM+ Applications\Metastorm Process Engine". b. Right-click and add a new user (non-Admin account). These are accessible by expanding the Metastorm Process Engine node. 11. Open Windows Explorer and navigate to C:\Program Files\Metastorm\BPM\Engine. 12. Double-click eEngineW.exe. 13. The Engine should start without errors and an icon should appear in the system tray. 14. Start the Deployment Service. 15. Run the Designer. 16. Open the desired solution and click the Debug button. 17. Perform the debugging, and when finished: n n Press the Stop/Detach button in Visual Studio. Right-click the Metastorm Process Engine icon in the system tray, select "Shut down...", then click Yes. Setting Breakpoints in C# Code You can set breakpoints in the generated C# code displayed in Visual Studio. For example: 1. Place a breakpoint in the first line of the start action. 2. In the Web Client, when you open a blank form, Visual Studio captures the event and stops the process at the appropriate line. Control is transferred to Visual Studio. 3. At this point you will be able to hover over the code and find out the current values of Business Object items that you may have used. 4. To continue with the Web Client operations, stop the debugging operation by clicking the stop debugging button inside Visual Studio debug toolbar. To close Visual Studio, use File > Exit. Note: For breakpoints to work in Visual Studio 2010, go to Tools > Attach to Process > Select > Select "Debug these code types" > select the "Manages (v2.0, v1.1, v1.0)" option. Visual Studio 2010 selects v4.0 by default. Location of the C# files Depending on the OS, the generated C# files are saved to one of the following locations: 438 MBPM Designer User's Guide Chapter 38 Debugging l l %CommonAppData%\Metastorm\BPM\GeneratedSourceCode (Vista). C:\Documents and Settings\All Users\Application Data\Metastorm\BPM\GeneratedSourceCode (Windows XP). The source code is created under GeneratedSourceCodein in folders corresponding to the format AssemblyName\AssemblyVersion. Project Versions In the Repository, an icon is displayed next to debugged projects. There may be several versions of the project in the Repository depending on the number of times the project has been debugged. Projects Retention You can configure the Designer to retain the files that have been created when the project was debugged. The source code retention policy is configurable via the DeploymentService.exe.config file (located in Program files\Metastorm\BPM\Deployment\ folder). Currently, you can either delete all previous versions or perform no deletions at all. Troubleshooting This section provides information that will enable you to troubleshoot reasons why the debug button may not be visible in the Designer. Checklist 1. Ensure that the logged in user is listed under "Roles\Administrator\Users" of "\My Computer\COM+ Applications\Metastorm Process Engine". 2. The SQL Server must have the correct credentials in its 'Security->Logins' section. 3. Ensure both the Metastorm Engine and Deployment services are running. 4. Ensure that the MetastormDiagnosticsApppool is running under the ‘NetworkService’ account. 5. Check that the diagnostics feature is installed correctly, by opening the Add/Remove Programs and checking the BPM installation. 6. Open up the %mbpm%\Engine\Diagnostics\ProcessDiagnostics\Web.Config, and make sure that the connection string is correct. (This can be checked against the deployment service config connections string). 7. Open the Designer, go to 'Options' and enter the correct URL to the process diagnostics service. //localhost/ProcessDiagnosticsService/ProcessDiagnostics.svc 8. Open the Designer, and check for warning messages in the ‘Messages’ pane. Debugging in Windows XP The Debug button may not be displayed on Windows XP machine even though the prerequisites for using the debug feature are installed. To overcome this situation: MBPM Designer User's Guide 439 Chapter 38 Debugging 1. After starting Designer, open Event Viewer -> Applications, open last event log with type 'Failure Audit', and copy user name to clipboard. For example: The log displays, "Login failed for user '<USERNAME\USERMACHINE>'. [CLIENT: <local machine>]" 2. Open SQL Server Management Studio and connect to database engine with your MBPM database. 3. Go to Security->Logins and add the user found in step 1 (<USERNAME\USERMACHINE>) with 'sysadmin' server role. 4. Restart Designer to view and use the Debug button. 440 MBPM Designer User's Guide Chapter 39 Troubleshooting Chapter 39 Troubleshooting Code Generation Error Troubleshooting When code generation errors occur, error messages will be displayed in the form of a tool tip appearing from the right of the status bar. Clicking the message will display further error information in the Messages pane and takes the user to the source of the error. Deployment Internal Error If you set SQL Server option "xact abort" to TRUE, restart it, and open Designer to deploy any new process, an error message "Deployment internal error" is displayed. To overcome this error message, the SQL Server setting "xact abort” should always be set to FALSE. MBPM Designer User's Guide 441 442 MBPM Designer User's Guide Chapter 40 Process Activator Chapter 40 Process Activator Introduction to Process Activator The Process Activator guides you through the steps to activate a process as a web service and publish it. It is accessed from External Applications tab from the ribbon bar within the Designer or from the Start menu. Process Activator screens The Process Activator guides you through the following screens: 1. Welcome screen – choose to connect to the default metadata web service. 2. Create connection screen – configure the process metadata service. 3. Select process screen- select the process to activate. 4. Select Stages and Action screen- select the stages / actions to activate. 5. Select location screen- specify the location of the web service and the publication filter. 6. Publish Web Service screen – publish the web service. 7. Activation complete screen – see a summary of activated process. Each screen is described in more detail below: Connect to the default metadata web service (Welcome screen) The Welcome screen provides the steps that you need to take complete process activation. If you select the option to connect to the default metadata web service, you will not need to configure the process metadata service. You may skip the next screen in the Process Activator. Connection Parameters Option Summary Alias (string) This is a user defined name for the Web Service. URL (string) The location of the Process Metadata Service. The default service name is displayed. It is obtained from the Process MBPM Designer User's Guide Remarks The MBPM Process Metadata Service can run on a separate engine machine. If this is the case, the MBPM Process Metadata Service 443 Chapter 40 Process Activator Option Type Summary Remarks Activator’s and VS Integration configuration files. will need to link to the engine. The authentication used by the MBPM Process Metadata Service. The following authentication methods are supported: l l l User name (string) Sets the user name used for basic authentication. Password (string) Sets the password used for basic authentication. Domain (string) Sets the domain used for basic authentication. Default Configuration (boolean) Sets the displayed Web Service as the default Process Metadata Web Service. The alias name of the default configuration is moved to the top of the Alias drop-down. Anonymous - a dedicated local account is used to service the request. Basic Authentication (requires User name, Password and Domain) Integrated Windows Authentication, the default. The service impersonates the credentials of the user accessing the service. Remember that password information is sent in plain text over the network when using basic authentication. Proxy Details Option Summary Remarks Use Sets the information Proxy for the proxy server (boolean) used for all web services calls. Type 444 Sets the proxy type. l The proxy server can be configured into two ways: MBPM Designer User's Guide Chapter 40 Process Activator l l CURRENT_USER - the current user’s IE settings are used to determine the proxy. host:port -the proxy at host:port is used (for example. http://93.13.17.2:8080). These settings override the IE settings. Host The host port of the Http must be used in front of definition. proxy. For example: http://93.13.17.2:8080 . User name (string) Sets the username used when accessing the proxy server. Password (string) Sets the password used when accessing the proxy server. Bypass if local address (boolean) Determines whether the proxy server is bypassed when calling local resources. If checked, requests to local Internet resources do not use the proxy server. Local requests are identified by the lack of a period (.) in the URI, as in http://webserver/ or access the local server, including http://localhost, http://loopback, or http://127.0.0.1 . If not checked, all Internet requests are made through the proxy server. Buttons Options Remarks Add or Update This button adds or updates the displayed web service configuration details. Delete This button deletes the displayed web service configuration details. In the Process Activator, the web service connection is tested when the user clicks Next. Configure the process metadata service (Create connection screen) l l l Default values are provided in the fields. If you did not check the option ‘connect to the default metadata web service’, you will need to define the configuration of the process metadata service. If you are connecting through a proxy, enter the proxy details in this screen. MBPM Designer User's Guide 445 Chapter 40 Process Activator Select the process to activate (Select process screen) l l l A list of all the processes available on the selected service will be displayed. On highlighting a process, the details of this process will be displayed. This information will help you in identifying the process that has been selected. When a process has been selected, you can continue to select the stages and actions of this process that will be activated. Select the stages and actions to activate (Select stages and actions screen) For the process selected, the actions and stages will be displayed. You can select one or more actions and stages. On highlighting an action or stage, the details of this control and the form fields associated to the control will be displayed. Specify the location of the web service and the publication filter (Select location screen) You can browse to the location where the web service will be stored. You can also select the service publication filter, if the web service is going to be published. Publish the Web Service (Publish Web Service screen) If you have selected to publish to a web service, enter the UDDI and publication information. Summary of activated process (Activation complete screen) The final screen of the Process Activator displays a summary of what has been included in the activated process. Note: Some of the new controls introduced in version 9.1 will not be supported in clients other than the Web Client. The unsupported controls are as follows: l Person l Panel l Rich Text If these controls or a Grid control containing these column types are used as required fields in a Form, actions on it will fail to submit in an external client. Activated Process as a Web Service You can activate a process and deploy it as a Web Service. The following is an example describing the steps involved in activating the sample process and consuming it from Visual Studio. Activating the Sample Process To activate the sample process: 1. In the Designer, open the StormzoSolution from C:\Program Files\Metastorm\BPM\Sample Processes\Sample 1. 2. Deploy the solution. 446 MBPM Designer User's Guide Chapter 40 Process Activator 3. Open the Process Activator from the External Applications ribbon tab. 4. Follow the steps mentioned in Introduction to Process Activator to activate the Registry process of the StormzoSolution by selecting all stages and actions. The Registry process is activated and a web service will be generated. To use Visual Studio to consume the Web Service: 1. Start Visual Studio. 2. In your .NET solution, add a Service Reference from the Solution Explorer. 3. Provide the following details: n n n In the Namespace field, enter Stormzo. In the Address field, locate the Registry service. For example: http://localhost/Registry.svc. Select the Registry service. 4. Click OK. 5. In the code, perform these steps: a. Instantiate the Service Client. Stormzo.RegistryServiceClient stormzoService = new Stormzo.RegistryServiceClient(); b. Pass the user name and password. FormField[] loginData = new FormField[] { new TextField() { Name = "username", Value = "Sysadmin", Culture = CultureInfo.InvariantCulture.ToString() }, new TextField() { Name = "password", Value = PasswordEncrypt ("Metastorm"), Culture = CultureInfo.InvariantCulture.ToString() } }; c. Retrieve the session state. ServiceSessionState 0, "", loginData); eclServiceSession = stormzoService.Login("WEB;", d. Start an action. BlankFormsRegistrationFormAction bfAction = stormzoService.StartBlankFormsRegistrationForm(eclServiceSession); e. Populate field with data bfAction.Fields.TxtEmail.Value = txtEmail.Text; bfAction.Fields.TxtPassword.Value = txtPassword.Text; bfAction.Fields.TxtConfirmPassword.Value = txtConfirmPassword.Text; bfAction.Fields.TxtTitle.Value = txtTitle.Text; bfAction.Fields.TxtFirstName.Value = txtFirstName.Text; bfAction.Fields.TxtSurname.Value = txtSurname.Text; MBPM Designer User's Guide 447 Chapter 40 Process Activator bfAction.Fields.TxtAdd1.Value = txtAddress1.Text; bfAction.Fields.TxtAdd2.Value = txtAddress2.Text; bfAction.Fields.TxtAdd3.Value = txtCity.Text; bfAction.Fields.TxtPostcode.Value = txtPostcode.Text; bfAction.Fields.TxtTelephone.Value = txtTelephone.Text; bfAction.Fields.Country.Value = rbCountryUS.Text; bfAction.Fields.TxtcreditCard.Value = rbUserOtherCCCard.Text; f. Submit the form. stormzoService.SubmitBlankFormsRegistrationForm ( eclServiceSession, bfAction ); g. Log out. stormzoService.Logout(eclServiceSession); 6. Run this solution from Visual Studio. 7. Access the MBPM Web Client, and go to the To Do list. The information that you have submitted through Visual Studio is displayed when you open the related Registry folder from the To Do list of the MBPM Web Client. Allow Activated Process Web Service Access through SSO To allow activated process web service access through SSO: 1. Set the following authentication settings in IIS for the web service application: l ASP.NET Impersonation l Windows Authentication 2. Edit the generated web service’s web.config: In the <basicHttpBinding> section update the security node for each binding to be as follows: <security mode="TransportCredentialOnly"> <transport clientCredentialType="Windows" /> <message clientCredentialType="UserName" algorithmSuite="Default"></message> </security> In the <serviceBehaviors> section add the following line: <serviceAuthorization impersonateCallerForAllOperations="true"/> 448 MBPM Designer User's Guide Chapter 40 Process Activator 3. In the main service class file (<ProcessName>Service.cs) update the class <ProcessName>Service as follows: After the line eclSession = SessionHelper.CreateProxyInstance(); add the following: eclSession.ClientCredentials.Windows.AllowedImpersonationLevel = System.Security.Principal.TokenImpersonationLevel.Impersonation; Edit each method with the following attribute [System.ServiceModel.OperationBehavior(Impersonation = System.ServiceModel.ImpersonationOption.Allowed)] For example: [System.ServiceModel.OperationBehavior(Impersonation = System.ServiceModel.ImpersonationOption.Allowed)] public Metastorm.ECL.WebService.ServiceSessionState Login(string clientType, int currentSAP, string authenticationProcess, Metastorm.ECL.WebService.FormField[] loginData) 4. Edit the client’s app.config: l In the <basicHttpBinding> section set the security node to be as follows: <security mode="TransportCredentialOnly"> <transport clientCredentialType="Windows" /> <message clientCredentialType="UserName" algorithmSuite="Default"></message> </security> l In the calling code set Impersonation on the client object, for example: eclWs.ServiceClient ws = new ServiceClient(); ws.ClientCredentials.Windows.AllowedImpersonationLevel = System.Security.Principal.TokenImpersonationLevel.Impersonation; MBPM Designer User's Guide 449 450 MBPM Designer User's Guide Chapter 41 Document Management System Chapter 41 Document Management System MBPM provides Document Management System (DMS) integration to enable MBPM to route and manage documents stored in Document Management Systems. The following DMS providers are supported: l Microsoft SharePoint l OpenText Content Server For more information on versions of DMS supported, refer to the MBPM Installation and Configuration Guide. This feature adds DMS integration capabilities to the single attachment clip and multiple attachment clip controls. A library of integration functions (and Visual Script Activities) is also provided in this package. In order to make use of these integration functions in your scripts, this library must be deployed and referenced. For more information, refer to the DMS Libraries and Functions section. DMS Business Objects allow process designers to integrate with Content Server by defining lists of documents and binding those documents and their attributes to form fields. This facility is not currently supported for SharePoint. Setup For information on installing and configuring DMS, see MBPM Installation and Configuration Guide. The instructions differ depending on the supported Document Management System. DMS Features DMS Controls The Clip is used to activate DMS clips. There are two types of DMS clips: l DMS Single Attachment Clip l DMS Multiple Attachment Clip MBPM Designer User's Guide 451 Chapter 41 Document Management System DMS Single Attachment Clip To create a DMS Single Attachment Clip: 1. Open or create a form. 2. Add a Clip to the form. 3. In the Clip Properties, check Document management support. The clip changes to a DMS Single Attachment Clip icon. 4. Set the DMS Multiple Attachment Clip Properties. Note: If you use an attachment clip to delete a document from SharePoint or Content Server, the file is deleted immediately, regardless of whether or not the form on which the attachment clip is placed on, has been submitted. However, when using a native attachment clip, any changes (such as upload, delete, and so on) are rolled back if the form is not submitted. DMS Multiple Attachment Clip This clip enables users to assign multiple attachments to a folder. The attachments are uploaded individually. To create a DMS Multiple Attachment Clip: 1. Open or create a form. 2. Click the MultiClip button. 3. In MultiClip Properties, select Document management support. The Clip changes to a DMS Multiple Attachment Clip icon. 4. Set the DMS Multiple Attachment Clip Properties. DMS Properties The Properties Editor has the following options that are relevant to DMS: l l DMS Provider – An option denotes the name of the DMS Provider. Document management support – An option is selected to enable DMS support and provide access to SharePoint system for users. If this option is checked, the Upload and Select options become available for Process user. The document management support option also provides access to other DMS properties in the Designer, such as Edit only mode and Default Location. l l Edit only – If this option is selected, the Remove and Delete menu options are not available to the Process User. Once a document has been uploaded or selected in a single clip, the options Upload and Select are also unavailable. Default Location – An option defines the default location to the document repository folder. 452 MBPM Designer User's Guide Chapter 41 Document Management System Introduction to DMS Business Objects for Content Server DMS Business Objects provide Process Developers the ability to connect to a Content Server instance and bind document metadata to fields on forms (in the same way as other types of Business Objects). When defining a DMS Business Object, the set of document attributes is selected. Then, when binding these business objects to forms, the attributes (document metadata) can be associated with form fields. DMS Business Objects are read-only. So, it is not possible to update document metadata directly through the Business Object. Creating a Content Server DMS Connection To establish a new connection with a Content Server, use the Connection component. 1. On the Home ribbon tab, Components group, click on the Connection button. 2. Select the Type of connection and select Document Management System. 3. From the Define Connection tab, enter the Content Server DMS Provider configuration properties as listed in the following table: Property Name Description Document Management System Content Server DMS Provider for MBPM (provided by default). Content Web Services URL The base URL of the OpenText Content Web Services (CWS) configured under Runtime & Core Services (RCS) in the supported Application Server, for example, Apache Tomcat or SAP NetWeaver. Content Web Services Suffix The Content Web Services (CWS) suffix, .svc for the .NET CWS and no suffix for the Java CWS. Currently, the Content Server DMS Provider only supports the Java CWS. Content Server Base URL The base URL to the OpenText Content Server installation. MBPM Designer User's Guide 453 Chapter 41 Document Management System Property Name Description OTDS Server URL and Port The base URL to the Runtime & Core Services (RCS) and OpenText Directory Services (OTDS) installation in your Application Server. Content Server resource id The resource id of the OpenText Local Runtime & Core Services (RCS). 4. Select the Preview tab and click Refresh to display a tree view of the available Content Server DMS attributes. For more information, refer to Navigating the Attributes Tree. 5. Click Test Connection to test your connection. If connection succeeds, a 'Connection successful' message is displayed. Creating DMS Business Objects Create a DMS Business Object in the main Business Objects pane by following the steps defined in Creating Custom Business Objects section. These are summarized as follows: 1. On the Home ribbon tab, Components group, click on the Business Object button. The Business Object main pane displays all the custom Business Objects that exist within the project. You can edit existing Business Objects using in-place editing. 2. Click in the Name field and enter a name for the Business Object (optional). 3. In the Type field, click and select the DMS connection type from the drop-down list. 4. Click in the Connection field. 5. Click . 6. Select DMS from the drop-down list. 7. Define the DMS Business Object Attributes as described in DMS Business Objects Attributes and Variables. 8. Click the MBPM button > Save. DMS Business Objects Attributes and Variables The DMS Business Object Attribute tab defines Category and Attribute Metadata. l l Category - A category is a folder that enables grouping of related folders and attributes. Attribute - An attribute is a data item related to an attribute definition (for example, ID, Create Date, Name). This information is associated with a document stored within the Content Server system and is made available to various column types within a DMS Grid. 454 MBPM Designer User's Guide Chapter 41 Document Management System Navigating the Attributes Tree Select the Attributes tab to display the Content Server repository tree. This consists of category folders and attributes. Category folders can contain child folders. To expand and collapse the Attributes Tree: 1. Click the plus sign on the System Attributes folder to expand the tree. This displays all category folders and attributes. 2. Click the minus sign on a folder to collapse the view for that particular folder. System Attributes The following are system attributes, which are available on all documents. l Create date l Create By l Display Type l ID l Modify Date l Name l Nickname l Type l Shortcut l Location MBPM Designer User's Guide 455 Chapter 41 Document Management System Attribute Data Types Attributes of the following types exist within the Content Server system. l Date l Time l Date Time l Currency l Check l List l Double Assigning Variable Names to Attributes Create variables by selecting them from the Available Attributes pane in the DMS Attributes pane and copying them to the Added Attributes pane. To create a variable from an attribute: 1. Select the attribute in the Available Attributes pane. 2. Click Add to copy the attribute to the Added Attributes pane. This action creates variables and makes them available in the Variable names tab. 3. Click Remove to remove the attribute from the Added Attributes pane. The variable is also removed from the Variable Names tab. The variables created from the Attributes tab are available as columns within a DMS Multi-Clip. Using Content Server Business Objects on Forms You can create a Content Server DMS enabled Multi-Clip by selecting the variables created from the DMS Business Object created earlier and creating a grid. Note: The Process Designer can also bind the DMS Business Object to fields and controls other than Multi-Clips. To create a DMS Multiple Attachment Clip for Content Server: 1. Follow the steps described in DMS Multiple Attachment Clip under DMS Features. 2. Assign variables as described in DMS Business Objects Attributes and Variables to columns in the grid. The grid columns appear in the Web Client at runtime. Note: When using multiple DMS Business Objects, DMS Multi-Clips combine all documents and display the same documents in every DMS Multi-Clip, even when added separately during an action. 456 MBPM Designer User's Guide Chapter 41 Document Management System Opening Content Server Attachment When you click on the “File Name” column entry, DMS Clip, or DMS Multi-Clip to open an attached Content Server document, by default, the Document Overview Page in Content Server opens. To change this default behavior, you can make one or both or the following changes: l Disable Document Overview –For details, refer to the Configuring Presentation Settings page of the Open Text Content Server Administrator Online Help from the OpenText Knowledge Center. Note: Disabling Document Overview will only display the selected document as an icon in a browser with the options to edit, download, or add comments. You must enable the “Open” document function, described in the next step, to open the document in the browser or a native application. l Enable “Open” document function – To open a selected document in the browser or a native application, refer to the Configure Security Parameter section of the Open Text Content Server Administrator Online Help from the OpenText Knowledge Center. DMS Libraries and Functions A library of DMS specific integration functions (and Visual Script Activities) are provided in this package. These functions allow DMS operations to be performed by BPM processes. In order to make use of these integration functions in your scripts, this library must be deployed and referenced in the current project. The following libraries are provided: Library Location Common DMS Functions Library C:\Program Files\ Metastorm\BPM\Administrative Tools\Administrative Processes\DMS\ContentServerDmsLibrary SharePoint DMS Functions Library C:\Program Files\Metastorm\BPM\Administrative Tools\Administrative Processes\Office Content Server DMS Functions Library C:\Program Files\Metastorm\BPM\Administrative Tools\Administrative Processes DMS Functions The DMS functions are: l Get Document Id l Get Folder Document Ids MBPM Designer User's Guide 457 Chapter 41 Document Management System Get Document Id Retrieves the document Id from a DMS clip. This function only works with the DMS Single Attachment Clip. Parameter Name Description Variable Select the custom variable that is mapped to the DMS single attachment clip. Returns Text data type. Get Folder Document Ids Returns a delimited list of document Ids attached to the current folder. Parameter Name Description List Delimiter A delimiter to separate the document Id list items. Returns Memo data type. Note: This function could be returned into a list field with the list delimiter set to the same delimiter type defined in the function. SharePoint Functions The SharePoint functions are: l Browse SharePoint l Check In Document l Check Out Document l Delete Document l Download Document l Get Document Author l Get Document Checked Out By l Get Document Creation Date l Get Document Editor l Get Document Last Modified l Get Document Metadata l Get Document Title l Move Document l Set Document Metadata l Undo Check Out Document l Upload Document 458 MBPM Designer User's Guide Chapter 41 Document Management System l Verify Document l Verify Folder Browse SharePoint This function can browse a specific DMS location. Parameter Name Description SharePoint Location The URL of a SharePoint library, folder, or site. Returns the Document Management System location in an XML fragment as a memo data type. Check In Document Checks in a document to the Document Management System. Parameter Name Description File Name The URL of the file to check in. Comments Comments to include with the checked in version of the document. Returns Integer data type. Check Out Document Checks out a document from the Document Management System. Parameter Name Description File Name The URL of the file to check out. Returns Integer data type. Note: If a document is already checked out a message is displayed to inform the user. Delete Document Deletes a document from the Document Management System. Parameter Name Description File Name The URL of the file to delete. Returns Integer data type. MBPM Designer User's Guide 459 Chapter 41 Document Management System Download Document Downloads a document from the Document Management System to the local file system. Parameter Name Description File Name The URL of the file to download. Local File Name Enter the full path and file name where to save the document on the local file system. Returns Integer data type. Get Document Author Returns the author of the document. Parameter Name Description File Name The URL of the file to return the document author. Returns Text data type. Get Document Checked Out By Returns the name of the user who has the document checked out. Parameter Name Description File Name The URL of the file to return the name of the user who has checked the file out. Returns Text data type. Get Document Creation Date Returns the creation date of the document. Parameter Name Description File Name The URL of the file to retrieve the creation date. Returns Date/Time data type. Get Document Editor Returns the name of the user who modified the document. 460 MBPM Designer User's Guide Chapter 41 Document Management System Parameter Name Description File Name The URL of the modified file. Returns Text data type. Get Document Last Modified Returns the last modified date of the document. Parameter Name Description File Name The URL of the file to return the last modified date. Returns Date/Time data type. Get Document Metadata Retrieves metadata for the document. Parameter Name Description File Name The URL of the document to query for metadata. Metadata Column A comma-separated list of metadata field name(s) to retrieve. Returns List data type. Note: You can use the following metadata columns: Metastorm default column names : Title, Modified, ModifiedBy, Created, CreatedBy, CheckedOutTo, and CheckInComment. Custom column names - use the display name. The custom column name is case sensitive. System column name - for example, vti_sourceversioncontrol. Refer to the Microsoft SharePoint SDK help for a list of system column names. For example: Title;vti_sourceversioncontrol;ModifiedBy Get Document Title Returns the document title of the document. Parameter Name Description File Name The URL to the file which the title is to be returned. Returns Text data type. MBPM Designer User's Guide 461 Chapter 41 Document Management System Move Document Moves the document to a new location. Parameter Name Description File Name The URL to the file which is to be moved. Location The URL of the target location. Document Name The document name at the target location. Set Document Metadata Sets metadata values for the document. Parameter Name Description File Name The URL of the file to modify. Metadata Column The metadata column name to modify. Variable Select the variable containing the value to be assigned to the metadata column. The variable can contain any data type. Returns Integer data type. Note: Refer to Get Document Metadata for a list of valid column names. Undo Check Out Document Undoes the Document Management System document checkout and reverts the document to a pre check out state. Parameter Name Description File Name The URL of the file to undo from the checkout state. Returns Integer data type. Upload Document Uploads a document to the Document Management System. 462 MBPM Designer User's Guide Chapter 41 Document Management System Parameter Name Description Server File Name The name of the file to save on the server. Local File The full path and file name of the file to be uploaded. Server Location The location of the DMS Provider. Returns Text data type. Verify Document Verifies that a document exists. Parameter Name Description File name The URL of the file to verify. Returns Check data type. Verify Folder Verifies that a folder exists. Parameter Name Description Folder Name The URL of the folder to verify. Returns Check data type. Content Server Functions The following Content Server functions are available in the Expression Builder: l Browse Content Server l Check In Document l Check Out Document l Delete Document l Download Document l Get Content l Get Document Metadata l Get Node Status l Get Node Status from List l Move Document l Set Document Metadata MBPM Designer User's Guide 463 Chapter 41 Document Management System l Undo Checkout Document l Upload Document l Verify Connection l Verify Document l Verify Folder Note: The “User Name” parameter must be in the following format. {username}@{FQDN} Where {username} is the user name in the Content Server user partition of OpenText Directory Services that executes the DMS command and {FQDN} is the fully qualified domain name. Alternatively, use the “UserName” property of the ProcessContext business object. In this case, the Content Server Designer Library converts the domain\username format of the ProcessContext UserName property into the {username}@{FQDN}format that OpenText Directory Services expects. Browse Content Server Retrieves a string containing the contents of a Content Server location in XML format. Parameter Name Description DMS Connection Select a DMS connection. Server Location Enter a Content Server library, folder, or site as URL. User Name Enter a user name. Check In Document Check in document to the document library. Parameter Name Description DMS Connection Select a DMS connection. File Name Enter the URL to the file for check in. Comments Enter comments to include with the checked in version. User Name Enter a user name. Returns True if the operation is successful; otherwise, returns False. Check Out Document Check document out from a document library. 464 MBPM Designer User's Guide Chapter 41 Document Management System Parameter Name Description DMS Connection Select a DMS connection. File Name Enter URL to the file for check out. User Name Enter a user name. Delete Document Deletes the document from Content Server. Parameter Name Description DMS Connection Select a DMS connection. File Name Enter the URL to the file to delete. User Name Enter a user name. Returns True if the operation is successful; otherwise, returns False. Download Document Downloads the document to the local file system. Parameter Name Description DMS Connection Select a DMS connection. File Name Enter the URL to the file to download. Local File Name Enter the full path where to save the document on the local file system. User Name Enter a user name. Get Content Retrieves a node by ID. This can be a unique value or a URL with all the associated data. Parameter Name Description DMS Connection Select a DMS connection. ID Enter a location or an ID, depending on the DMS for setting a unique identifier for locating the node. MBPM Designer User's Guide 465 Chapter 41 Document Management System Parameter Name Description User Name Enter a user name. Get Document Metadata Retrieves the metadata column(s) for a file. When retrieving custom metadata, use the following format for the metadata column parameter: ' {Category Volume}/{Category Group(s) or Folder(s)}/{Category Name}/ {Attribute Set Name}/{Attribute Name} The metadata column can contain multiple metadata field names. In the following example, the metadata column uses CreatedDate and Description as metadata field names and passes them as a list to Content Server. new List( new string[] { "CreatedDate", "Description", "CategoriesWS/Sample Category 3/Sister/Name" } ) Parameter Name Description DMS Connection Select a DMS connection. File Name Enter the full path to the document to query for metadata. Metadata Column Enter a comma-separated list of metadata field name (s). User Name Enter a user name. Returns List data type. Get Node Status Gets the node status by the ID. Parameter Name Description DMS Connection Select a DMS connection. ID Enter a user ID. User Name Enter a user name. Get Node Status from List Gets the node status by the list of IDs. 466 MBPM Designer User's Guide Chapter 41 Document Management System Parameter Name Description DMS Connection Select a DMS connection. IDs Enter a list of user IDs. User Name Enter a user name. Move Document Moves the document to another location within Content Server. Parameter Name Description DMS Connection Select a DMS connection. File Name Enter the URL to the file to move. Location Enter the new location to move the document to. Document Name Enter the name to save the document under the new location. User Name Enter a user name. Returns True if the operation is successful; otherwise, returns False. Set Document Metadata Assigns a value to a metadata column. When modifying custom metadata, use the same format as the metadata column parameter of Get Document Metadata. Note: The metadata column name in Set Document Metadata accepts single column names only. You can use the following default names with Get Document Metadata and Set Document Metadata: CreatedDate, Description, DisplayType, ID, ModifiedDate, Name, Nickname, Type, ShortLink, Location. Parameter Name Description DMS Connection Select a DMS connection. File Name Enter the full URL of the file to modify. Metadata Column Enter the meta data column name to modify. MBPM Designer User's Guide 467 Chapter 41 Document Management System Parameter Name Description Variable Select the variable whose value is to be assigned to the meta data column. User Name Enter a user name. Returns Check data type. Undo Check Out Document Undo the check out of a document. Parameter Name Description DMS Connection Select a DMS connection. File Name Enter URL to the file for check out. User Name Enter a user name. Returns True if the operation is successful; otherwise, returns False. Upload Document Uploads or updates a File to Content Server. Parameter Name Description DMS Connection Select a DMS connection. Server Location Enter the name of the file to save on the server. Local File Enter the full path to the file to upload. User Name Enter a user name. Verify Connection Verifies if a valid connection to the DMS provider is possible, using the authentication mechanism. Parameter Name Description DMS Connection Select a DMS connection. Returns Check data type. Verify Document Verifies if the file exists. 468 MBPM Designer User's Guide Chapter 41 Document Management System Parameter Name Description DMS Connection Select a DMS connection. File Name Enter a URL to the file for verification. User Name Enter a user name. Returns True if the operation is successful; otherwise, returns False. Verify Folder Verifies if the folder exists. Parameter Name Description DMS Connection Select a DMS connection. Folder Name Enter a URL to the folder for verification. User Name Enter a user name. Returns True if the operation is successful; otherwise, returns False. Content Server DMS Provider Activities The following is a list of the Content Server DMS Provider activities: l Get Node Status l Get Node Status from list l Get Root Node Types l Verify Connection l Get Contents l Populate Contents l Get Content l Upload Document l Browse Content Server l Check In Document l Check Out Document l Create Folder l Delete Folder l Move Document l Delete Document l Download Document l Get document Metadata l Set document Metadata MBPM Designer User's Guide 469 Chapter 41 Document Management System The following section describes the activities and its properties. Note: The “User Name” property must be in the format expected by the OpenText Directory Service (OTDS). Refer to Content Server Functions for further information regarding the required format. All Activities The following properties are applicable to all the Activities in the Content Server DMS Provider Activities: Property Name Description Name Enter a unique name to identify this activity in the Visual Script. Caption Enter a caption for the Activity. The caption is the text that is displayed for the Activity in the Visual Script. Description Enter a description for the Activity. Enabled Select to enable/disable the Activity. Get Node Status Gets the node status by the ID. Property Name Description DMS Connection Select a DMS connection. ID Enter a user ID. User Name Enter a user name. Get Node Status from List Gets the node status by the list of IDs. Property Name Description DMS Connection Select a DMS connection. IDs Enter a list of user IDs. User Name Enter a user name. 470 MBPM Designer User's Guide Chapter 41 Document Management System Get Root Node Types Gets the root node types. Property Name Description DMS Connection Select a DMS connection. Verify Connection Verifies if a valid connection to the DMS provider is possible, using the authentication mechanism. Property Name Description DMS Connection Select a DMS connection. Get Contents Retrieves a node by ID which can be a unique value or a URL with all the associated data. Property Name Description DMS Connection Select a DMS connection. Contents IDs Enter a list of content IDs. They can either be a location or an ID, depending on the DMS for setting a unique identifier for locating the node. User Name Enter a user name. Populate Contents Populates the child contents of a mode in the Content Server tree. Property Name Description DMS Connection Select a DMS connection. Content Option Enter a node to retrieve the child contents. User Name Enter a user name. Get Content Retrieves a node by ID which can be a unique value or a URL with all the associated data. MBPM Designer User's Guide 471 Chapter 41 Document Management System Property Name Description DMS Connection Select a DMS connection. ID Enter a location or an ID, depending on the DMS for setting a unique identifier for locating the node. User Name Enter a user name. Upload Document Uploads or updates a File to Content Server. Property Name Description DMS Connection Select a DMS connection. Server Location Enter the name of the file to save on the server. Local File Enter the full path to the file to upload. User Name Enter a user name. Browse Content Server Retrieves the contents of a Content Server location in XML format. Property Name Description DMS Connection Select a DMS connection. Server Location Enter a Content Server Library, Folder, or Site as URL. User Name Enter a user name. Check In Document Check in document to the document library. Property Name Description DMS Connection Select a DMS connection. File Name Enter the URL to the file for check in. 472 MBPM Designer User's Guide Chapter 41 Document Management System Property Name Description Comments Enter comments to include with the checked in version. User Name Enter a user name. Check Out Document Check document out from a document library. Property Name Description DMS Connection Select a DMS connection. File Name Enter URL to the file for check out. User Name Enter a user name. Create Folder Creates a folder in Content Server. Property Name Description DMS Connection Select a DMS connection. Location Enter the full path where the folder is to be created in the Content Server workspace. Folder Name Enter the folder name. User Name Enter a user name. Returns IDmsContent type. Delete Folder Deletes a folder in Content Server. Property Name Description DMS Connection Select a DMS connection. Folder Name Enter the path of the folder to delete. User Name Enter a user name. Returns Check Type (True or False). MBPM Designer User's Guide 473 Chapter 41 Document Management System Move Document Moves the document from one location to another within Content Server. Property Name Description DMS Connection Select a DMS connection. File Name Enter the URL to the file to move. Location Enter the new location to move the document to. Document Name Enter the name to save the document under the new location. User Name Enter a user name. Delete Document Deletes the document from Content Server. Property Name Description DMS Connection Select a DMS connection. File Name Enter the URL to the file to delete. User Name Enter a user name. Download Document Downloads the document to the local file system. Property Name Description DMS Connection Select a DMS connection. File Name Enter the URL to the file to download. Local File Name Enter the full path where to save the document on the local file system. User Name Enter a user name. Get Document Metadata Retrieves the metadata column(s) for a file. 474 MBPM Designer User's Guide Chapter 41 Document Management System Property Name Description DMS Connection Select a DMS connection. File Name Enter the full path to the document to query for meta data. Metadata Column Enter a comma-separated list of metadata field name (s) to retrieve. User Name Enter a user name. Set Document Metadata Assigns a value to a metadata column. Property Name Description DMS Connection Select a DMS connection. File Name Enter the full URL of the file to modify. Metadata Column Enter the meta data column name to modify. Variable Select the variable whose value is to be assigned to the meta data column. User Name Enter a user name. MBPM Designer User's Guide 475 476 MBPM Designer User's Guide Chapter 42 Accessiblity Chapter 42 Accessiblity Designing an accessible process The MBPM Process Engine is accessible to users with disabilities. This chapter describes points to consider when designing accessible processes. Section 508 In 1998, American Congress updated section 508 of the Rehabilitation Act of 1973 to reflect a focus on technology. Section 508 aims to provide employees with disabilities access to the same systems and information as those without disabilities. Enforceable standards were put in place that define what makes a product considered accessible to people with disabilities. For further information on Section 508 refer to www.section508.gov. Keyboard navigation It is possible to navigate through most of the MBPM Process Engine using only the keyboard. The following are exceptions where a mouse must be used: l Date picker l Time picker The date and time pickers are visual controls which can be used to select a date or time. Date and time fields can be completed using the keyboard. Using a keyboard to move through the items of a drop-down which has dependants causes each dependant field to be updated. We therefore recommend using a button to update the required field. Internet Explorer Text Size Setting the text size in Internet Explorer affects the text in the MBPM Process Engine To Do, Watch, Blank Forms or Admin Forms list, but does not affect form content. This is under the control of the process developer. The process developer may set the font size of text in an MBPM form using the options on the form’s Property Editor. Doing this will affect each field’s associated label, the text within each field and the size of each field. The process developer must set the font size of label fields separately, using the Font option on the label’s Property Editor. MBPM Designer User's Guide 477 Chapter 42 Accessiblity JAWS Support An unsighted user may use the MBPM Process Engine with the aid of the JAWS screen reader. When designing procedures that will be accessed by JAWS users, be aware of the following: Placing fields When JAWS reads the contents of a form to the user, it reads the contents in the order in which the fields appear on the form (from the top left to the bottom right). You can aid the user by aligning each field caption to the left or top of the field. This will ensure that JAWS reads any useful information about the field before reaching the field itself. Form fields JAWS announces regular HTML field types to the user. It tells the user the field type, and in some cases provides instructions on how to populate the field. In MBPM there are some complex field types that are made up of several HTML commands. JAWS does not know how to announce these MBPM specific fields. Make use of field captions and labels to help the user complete these fields. MBPM specific fields include: l Clips The buttons on multiple attachment fields allow you to add, open and delete attachments. These can be accessed by the TAB key. l Currencies l Date times l Grids l Rules l Numbers l Signatures l Status Invalid Characters If the user attempts to enter a letter into a Number or Currency field, JAWS reads out the letter but MBPM does not display the letter in the field. The user must tab out and back into the field to find out which characters have been successfully entered. It may be helpful to include a Label next to the field, which suggests that the user checks the contents of the field before submitting the form. If the user enters an invalid character into a masked Edit field, a Number or a Currency field with the Min or Max property set, JAWS reads out the character, and MBPM displays it in the field and allows other characters to be entered. When the user tabs out of the field a message is displayed that states that the field data is invalid. JAWS reads out this message. The user will not be able to submit the form until the data in the field is valid. 478 MBPM Designer User's Guide Chapter 42 Accessiblity Configuring JAWS JAWS users will need to configure their JAWS keyboard options. JAWS uses the INSERT key as a ‘modifier’ key. INSERT is pressed in combination with other keys to activate commands. MBPM uses the INSERT key to allow you to insert a row into an editable grid. To insert a row into an editable grid when running JAWS, configure JAWS to use just the numeric keypad INSERT as the JAWS modifier key. This leaves the extended INSERT key free for use in an editable grid. Navigating to the submit and cancel buttons on a form To access submit or cancel buttons in a form, use TAB key. For further information on keyboard navigation of the MBPM Web Client see the MBPM Web Client User's Guide. MBPM Designer User's Guide 479 480 MBPM Designer User's Guide Chapter 43 MBPM Reserved Words Chapter 43 MBPM Reserved Words The following table contains MBPM reserved words that should not be used for names of components, controls, and so on. Metastorm Integer Text Check List Declarations _parent Currency Memo Instances Type DateTime Real Flags Client MBPM Designer User's Guide FlagDataDeclarations 481 482 MBPM Designer User's Guide Chapter 44 OpenText Mobile BPM Chapter 44 OpenText Mobile BPM OpenText Mobile BPM provides users with the ability to initiate processes and monitor their process lists on a range of mobile devices. The following topics describe the MBPM Form controls that are supported in the Mobile Client and highlight the behavior of some of the MBPM Form controls in the Mobile Client. Supported Form Controls in Mobile Client The following form controls are supported in the Mobile Client: l Attachment Clip l Checkbox l Command Button l Currency l Date/Time l Drop-down l Form Segment l Image l Label l List l Memo l Multi-clip l Number l Panel l Radio Group l Status l Text Unsupported Features and Form Controls in Mobile Client The following features are not supported in the Mobile Client: l Chained actions l Client scripts MBPM Designer User's Guide 483 Chapter 44 OpenText Mobile BPM l Custom lists l Reopen folder l Reports The following controls are also not supported in the Mobile Client: l Grid l Person l Rich Text l Rule l Signature Field Behavior The following table lists the form controls and their properties that are not supported in the Mobile Client. Control Properties that are not supported Text Position, Width, Anchor, Caption Alignment, Field Alignment, On field entry, On field exit Label Position, Size, Anchor, Field Alignment, Font and its sub-properties (except Bold), Client Extension Button Position, Size, Anchor, Client Extension, Button Action>Client operations, When button pressed (Client script event handler) Number, Position, Width, Anchor, Caption Alignment, On field entry, On field exit, Client Extension Currency, Date/Time, Drop-down, Checkbox Image Position, Anchor, Size1,Client Extension, Description Memo Position, Size, Anchor, Caption Alignment, On field entry, On field exit, Client Extension 1 If the image is wider than the device screen, it is adjusted proportionally to the device screen width and height. If the image is narrower than the device screen, it is not adjusted. 484 MBPM Designer User's Guide Chapter 44 OpenText Mobile BPM Control Properties that are not supported Clip Position, Anchor, Client Extension, DMS Support Multi-clip Position, Size, Anchor, Client Extension, DMS Support, When user selects row Panel Position, Size, Anchor, Color, Dock Form Segment Position, Size, Anchor, Dock List Position, Size, Anchor, On field entry, On field exit, Client Extension Status Position, Anchor, On field entry, On field exit, Client Extension, Drill-down Note: Hint property is supported only on desktop browsers for the following controls: l Text l Button l Number l Memo l Clip l Multi-clip l List l Status Alignment In the Mobile Client, all form controls will be placed one below the other aligned ordered by the tab index values specified in the MBPM Designer. Action Description and Help URL To use Action description and Help URL properties: 1. Create a Process. 2. In the action's property pane, enter the following: l Description: Description of the action (For example, Check rating) l HelpURL: Static or dynamic URL (For example, "www."+ BO.variable +".com") where: l BO is a Business Object associated with the Process l variable is a Process Variable associated with BO. MBPM Designer User's Guide 485 Chapter 44 OpenText Mobile BPM 3. Save the process. 4. Deploy the process. 5. Open the Mobile Client. The action description is displayed as follows: The help URL is displayed as follows: Clicking on the help URL displays the help in a new tab. For some devices, such as Windowsbased phone, the help will open in the same window. Click 'Back' button to navigate back to the Form. Help URL button will be available when an action, associated with a form, is opened. If the action is not associated with any form, irrespective of whether the confirm action property is selected or de-selected, the URL will not be available. Command Button For a Command Button control in the MBPM Designer, ‘Button action’ property can be set to one of the following operations: l Cancel action l Commit action l Initiate a process l Open existing folder l Server operation Note: Client Scripts is not supported in the Mobile Client. The following topic describes the ‘Button action’ properties and its behavior in the Mobile Client. 486 MBPM Designer User's Guide Chapter 44 OpenText Mobile BPM l l l Cancel action: Cancels the form without saving any changes. Commit action: Updates the database with any changes made to the form and may move the folder to the next stage. When a commit action is performed, form is closed, action is committed, current stage is completed, and the next stage is started. Initiate a process: Opens the associated form in a new tab. After the form is submitted or canceled, the tab is closed and control is returned to the initiator form. Note: On some devices, such as Windows-based phone, a new tab is not opened. Instead, the form displays in the current tab. n When using a confirm action, a pop-up message displays. Click OK to confirm the action. A brief message displays to indicate that the action is submitted successfully. n l l When using a non-confirm action, a brief message displays to indicate that the action is submitted successfully. Open existing folder: Opens a folder created previously by this or another process, as specified in MBPM Designer. The folder opens in a new tab in the Mobile Client. Server operation: Uses the 'When button pressed' script specified in the MBPM Designer to perform an operation specified by the script. This is the default action. Attachment Clip The following topic describes the behavior of an attachment clip in the Mobile Client when form is opened at an action and a stage. Supported Devices The attachment clip is supported on the following devices: l Android l Blackberry l iOS 6 (upload pictures only) Attachment clip on a form at a stage Attachment clip on a form opened at a stage can have one of the following properties: l Read-only and empty l Read-only and non-empty When a form with an attachment clip is opened at a stage, the following restrictions apply: l Existing attached files can be opened and saved but cannot be deleted. l Files cannot be uploaded. To open or save an attachment, click the link to the attached file. If the file has a supported program installed, the file is opened with the associated program in the device. If not, you are prompted to save the file on your device. Note: On iPhone and iPad, unsupported file attachments cannot be opened or saved. Instead, a warning message is displayed. Attachment clip on a form at an action Attachment clip on a form opened at an action can have one of the following properties: MBPM Designer User's Guide 487 Chapter 44 OpenText Mobile BPM l Read-only and empty l Read-only and non-empty l Editable and empty l Editable and non-empty When a form with an attachment clip is opened at an action and the clip is editable, the following operations can be performed: l Attachment can be deleted. l File can be uploaded. l Attachment can be opened or saved. Features of an editable clip l l l An 'Add file' link is displayed to add a file to the attachment clip. Required attachment clip field has a red asterisk to the right of the caption of the clip indicating that the field cannot be empty. A red X button is displayed to the right of the clip to enable deleting the attachment. Note: DMS functionality of attachment clip and multi-clip controls are not supported in the Mobile Client. Multi Clip The multi-clip behavior and supported devices are similar to an Attachment Clip. Following are the exceptions: l Multiple files can be attached to a multi-clip. l Multi-clip fields do not have a caption. l l Required multi-clip field has a red asterisk next to the 'Add file' link indicating that the field cannot be empty. File size is displayed for files uploaded to a multi-clip. The 'When user selects row' property of the multi-clip control is not supported on the Mobile Client. Status Drill down to property is not supported for Status controls. The Safety Hint, Warning Hint, and Danger Hint properties are supported and shown as captions for status control for all devices. GPS To use GPS coordinates on a Form: 1. In MBPM Designer, add a text control to a form and set the text control's client extension property to GPS. 2. Open the form in the mobile device.You will be prompted to share your location. 488 MBPM Designer User's Guide Chapter 44 OpenText Mobile BPM If you allow to share your location, when the form is opened or refill operation occurs, the text control is populated with GPS coordinates of current location in the format: [Latitude], [Longitude]. For example, 43.17539, 42.27507.If 'Share location' is off or if you do not allow 'Share location', an error message is displayed. Click OK on the error and the form will open but the text field will not contain GPS coordinates. If a text control has the client extension property set to GPS and uses a calculated value, such as ProcessContext.ClientType, the GPS coordinates display on the form at an action in the process. The “Share location” setting must be on to display calculated values on the form at a stage in the process. If “Share location” is off, calculated values display on the form at action and stage in a process. When a form loads or a refill operation is performed, GPS data is displayed. However, form at a stage does not cause the text box to refresh. Note: If you used earlier versions of MBPM Mobile and used the realLat and realLong fields to display GPS data, you must update and redeploy your solutions to display GPS data. MBPM Mobile no longer supports realLat and realLong fields. MBPM Designer User's Guide 489 490 MBPM Designer User's Guide

MBPM Designer User's Guide

Related documents

Add this document to collection(s)

Add this document to saved

Suggest us how to improve StudyLib