Modeling - Whitestein Technologies

Modeling - Whitestein Technologies
Living Systems® Process Suite
Modeling
Living Systems Process Suite Documentation
3.2
Thu Sep 28 2017
Whitestein Technologies AG | Hinterbergstrasse 20 | CH-6330 Cham
Tel +41 44-256-5000 | Fax +41 44-256-5001 | http://www.whitestein.com
Copyright © 2007-2017 Whitestein Technologies AG
All rights reserved.
Copyright © 2007-2017 Whitestein Technologies AG.
This document is part of the Living Systems® Process Suite product, and its use is governed by the corresponding
license agreement. All rights reserved.
Whitestein Technologies, Living Systems, and the corresponding logos are registered trademarks of Whitestein
Technologies AG. Java and all Java-based trademarks are trademarks of Oracle and/or its affiliates. Other company,
product, or service names may be trademarks or service marks of their respective holders.
Contents
1
2
Main Page
1
1.1
2
Running Process Design Suite . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Modeling
5
2.1
Model Structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
6
2.1.1
GO-BPMN Projects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
7
2.1.1.1
Creating GO-BPMN Projects
. . . . . . . . . . . . . . . . . . . . . . . . . . .
7
2.1.1.2
Closing GO-BPMN Projects . . . . . . . . . . . . . . . . . . . . . . . . . . . .
8
2.1.1.3
Referencing Projects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
8
GO-BPMN Modules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
9
2.1.2.1
Creating GO-BPMN Modules . . . . . . . . . . . . . . . . . . . . . . . . . . .
9
2.1.2.2
Specifying Module Properties . . . . . . . . . . . . . . . . . . . . . . . . . . .
10
2.1.2.3
Importing Modules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
11
Definitions and Configurations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
14
2.1.3.1
Creating Definitions and Configurations . . . . . . . . . . . . . . . . . . . . . .
15
2.1.3.2
Opening Resource Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
15
Generic Modeling Mechanisms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
16
2.2.1
Writing Expressions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
17
2.2.1.1
Testing Expressions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
17
2.2.2
Defining Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
18
2.2.3
Disabling Elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
19
2.2.3.1
Defining Formatting of Disabled Elements . . . . . . . . . . . . . . . . . . . . .
22
Working with Diagrams . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
23
2.2.4.1
25
2.1.2
2.1.3
2.2
2.2.4
Creating a Diagram . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
iv
CONTENTS
2.2.4.2
Inserting Element Views . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
25
2.2.4.3
Aligning Element Views . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
27
2.2.4.4
Matching Element Views Size . . . . . . . . . . . . . . . . . . . . . . . . . . .
27
2.2.4.5
Spreading Diagram Element Views . . . . . . . . . . . . . . . . . . . . . . . .
28
2.2.4.6
Locating Element from a Diagram . . . . . . . . . . . . . . . . . . . . . . . . .
28
2.2.4.7
Changing Process Element Type . . . . . . . . . . . . . . . . . . . . . . . . .
29
2.2.4.8
Deleting Elements from Diagrams . . . . . . . . . . . . . . . . . . . . . . . . .
29
2.2.4.9
Snapping to Grid . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
29
2.2.4.10 Customizing the Palette . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
30
2.2.4.11 Displaying Page Borders . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
30
2.2.4.12 Diagram Elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
31
2.2.4.13 Formatting Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
35
2.2.4.14 Diagram Printing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
39
2.2.4.15 Aligning Diagram Elements . . . . . . . . . . . . . . . . . . . . . . . . . . . .
43
2.2.4.16 Applying Automatic Layout in Diagrams . . . . . . . . . . . . . . . . . . . . . .
43
Comparing Resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
45
2.2.5.1
Comparing Two Resources . . . . . . . . . . . . . . . . . . . . . . . . . . . .
46
2.2.5.2
Comparing Three Resources . . . . . . . . . . . . . . . . . . . . . . . . . . .
47
2.2.5.3
Comparing Version-Controlled Resources . . . . . . . . . . . . . . . . . . . . .
49
2.2.6
Todo and Task Markers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
50
2.2.7
Modeling Status . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
51
2.2.7.1
Setting Modeling Status . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
51
2.2.7.2
Defining Modeling Status
. . . . . . . . . . . . . . . . . . . . . . . . . . . . .
52
2.2.7.3
Defining Modeling Status for a Project . . . . . . . . . . . . . . . . . . . . . . .
52
2.2.7.4
Exporting and Importing Status Definitions . . . . . . . . . . . . . . . . . . . .
53
2.2.7.5
Disabling Modeling Statuses . . . . . . . . . . . . . . . . . . . . . . . . . . . .
53
Workspace Validation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
54
2.2.8.1
Problem Severity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
54
2.2.8.2
Configuring Workspace Validation . . . . . . . . . . . . . . . . . . . . . . . . .
54
2.2.8.3
Configuring Project Validation . . . . . . . . . . . . . . . . . . . . . . . . . . .
55
2.2.5
2.2.8
CONTENTS
2.2.9
2.3
2.5
2.6
2.7
2.2.8.4
Automatic Validation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
56
2.2.8.5
Manual Validation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
56
2.2.8.6
Validating Old Modules
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
56
2.2.8.7
Hiding Validation Markers . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
56
Search
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
56
2.2.9.1
Searching for GO-BPMN Entities and their Usage
. . . . . . . . . . . . . . . .
57
2.2.9.2
Searching for Elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
58
2.2.9.3
Searching for Element Usages
. . . . . . . . . . . . . . . . . . . . . . . . . .
58
2.2.9.4
Searching for Dependent Tasks . . . . . . . . . . . . . . . . . . . . . . . . . .
59
2.2.9.5
Searching for Call Hierarchies . . . . . . . . . . . . . . . . . . . . . . . . . . .
59
2.2.9.6
Searching for Unused Elements . . . . . . . . . . . . . . . . . . . . . . . . . .
59
Processes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
60
2.3.1
Creating a Process . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
60
2.3.2
Defining Element Labels . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
61
2.3.3
Defining Process Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
62
2.3.4
Defining Process Local Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
63
2.3.5
Inserting Tasks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
63
2.3.5.1
Changing Task Type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
64
2.3.5.2
Cleaning up Task Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . .
64
Extracting Process Elements into a Reusable Sub-Process . . . . . . . . . . . . . . . . .
64
Global Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
64
2.4.1
64
2.3.6
2.4
v
Defining Global Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Organization Models
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
65
2.5.1
Creating an Organization Model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
66
2.5.2
Assigning a Role or Organization Unit . . . . . . . . . . . . . . . . . . . . . . . . . . . .
67
Documents
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
67
2.6.1
Defining a Document . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
68
2.6.2
Navigate Away from Document . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
69
2.6.2.1
. .
70
Forms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
70
Creating a Model Instance and Navigating to its To-Do on Document Submit
vi
CONTENTS
2.7.1
2.7.2
2.7.3
2.7.4
2.7.5
Form Execution Levels . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
73
2.7.1.1
74
Evaluation Execution Levels . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Event-Processing Cycle
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
75
2.7.2.1
Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
77
2.7.2.2
Listeners . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
83
Creating Forms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
85
2.7.3.1
Defining Process Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . .
85
2.7.3.2
Defining Local Form Variables . . . . . . . . . . . . . . . . . . . . . . . . . . .
86
2.7.3.3
Designing Form Tree . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
86
2.7.3.4
Generic Actions on Forms . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
90
2.7.3.5
Creating CRUD Components . . . . . . . . . . . . . . . . . . . . . . . . . . .
93
2.7.3.6
Validating Form Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
96
2.7.3.7
Reusing Forms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101
2.7.3.8
Modifying Presentation of Components . . . . . . . . . . . . . . . . . . . . . . 110
2.7.3.9
Creating Mobile Forms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114
Component Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115
2.7.4.1
Container Components
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115
2.7.4.2
Input Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121
2.7.4.3
Output Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135
2.7.4.4
Action Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161
2.7.4.5
Special Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 162
2.7.4.6
Annotations
2.7.4.7
Deprecated Components
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 166
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 166
Patterns . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 169
2.7.5.1
Editable Table . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 169
2.7.5.2
Sortable Table . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 170
2.7.5.3
Table with Derived Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 173
2.7.5.4
Calendar with Adding Entries Functionality . . . . . . . . . . . . . . . . . . . . 176
2.7.5.5
Pop-up with Apply and Cancel Buttons . . . . . . . . . . . . . . . . . . . . . . 179
2.7.5.6
Validating Initialized Forms
. . . . . . . . . . . . . . . . . . . . . . . . . . . . 182
CONTENTS
2.7.6
2.8
2.9
vii
Enabling Error Reporting on Components . . . . . . . . . . . . . . . . . . . . . . . . . . 182
Localization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 183
2.8.1
Creating Localization Identifiers in the Localization Editor . . . . . . . . . . . . . . . . . . 183
2.8.2
Creating and Calling Localization Identifier in the Expression Editor . . . . . . . . . . . . . 184
2.8.3
Calling Localization Identifiers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 185
2.8.4
Searching for Usages of Localization Identifiers . . . . . . . . . . . . . . . . . . . . . . . 185
2.8.5
Identifying Unlocalized Strings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 186
Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 186
2.9.1
Calling Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 186
2.10 Task Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 186
2.11 Queries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 186
2.11.1 Standard Queries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 187
2.11.1.1 Filtering of Results in Standard Queries . . . . . . . . . . . . . . . . . . . . . . 188
2.11.1.2 Ordering in Standard Queries . . . . . . . . . . . . . . . . . . . . . . . . . . . 189
2.11.1.3 Generating Queries for Shared Records . . . . . . . . . . . . . . . . . . . . . . 191
2.11.2 Native Queries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 192
2.11.3 Calling Queries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 193
2.12 Data Type Model
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 193
2.12.1 Creating a Data Type Model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 194
2.12.2 Creating Records . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 194
2.12.3 Creating Record Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 195
2.12.4 Defining Record Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 196
2.12.5 Creating Record Subtypes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 196
2.12.6 Creating Record Relationships . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 197
2.12.6.1 Deleting Record Instances in a Data Relationship . . . . . . . . . . . . . . . . . 199
2.12.6.2 Creating Record Components . . . . . . . . . . . . . . . . . . . . . . . . . . . 200
2.12.7 Creating an Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 200
2.12.8 Comparing Records
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 201
2.12.8.1 Defining Fields Used in Record Comparisons . . . . . . . . . . . . . . . . . . . 201
2.12.8.2 Using Fields on Related Records Used in Record Comparisons . . . . . . . . . 202
viii
CONTENTS
2.12.9 Working with Record Diagrams . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 202
2.12.9.1 Displaying and Hiding Additional Compartments in Records . . . . . . . . . . . 202
2.12.9.2 Viewing Record Hierarchy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 203
2.12.10 Importing Data Types from an XSD File . . . . . . . . . . . . . . . . . . . . . . . . . . . 204
2.12.11 Validating Record Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 204
2.12.11.1 Defining Constraints . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 205
2.12.11.2 Defining Constraint Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 206
2.12.11.3 Filtering Applied Constraints using Tags . . . . . . . . . . . . . . . . . . . . . . 207
2.13 Persistent Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 208
2.13.1 Defining Database Properties
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 208
2.13.1.1 Extracting Shared Record Properties to Datatype Definition . . . . . . . . . . . 209
2.13.2 Generating Data Model from a Database Schema . . . . . . . . . . . . . . . . . . . . . . 210
2.13.3 Creating Shared Records . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 211
2.13.4 Creating Shared Record Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 212
2.13.4.1 Defining a Shared Field with a Foreign Key of a Related Record . . . . . . . . . 213
2.13.5 Data Relationships Between Shared Records . . . . . . . . . . . . . . . . . . . . . . . . 214
2.13.5.1 Fetching . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 214
2.13.5.2 Indexes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 215
2.13.6 Auditing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 216
2.13.6.1 Setting up Auditing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 217
2.13.6.2 Including a Shared Record in Auditing . . . . . . . . . . . . . . . . . . . . . . . 218
2.13.6.3 Excluding a Shared Field or Record from Auditing
. . . . . . . . . . . . . . . . 219
2.13.6.4 Excluding a Relationship End from Auditing . . . . . . . . . . . . . . . . . . . . 220
2.13.6.5 Working with Record Revisions . . . . . . . . . . . . . . . . . . . . . . . . . . 220
2.13.7 Caching Shared Records . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 220
2.13.7.1 Defining Cache Regions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 221
2.13.7.2 Disabling Cache Regions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 221
2.13.8 Change Proxy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 221
2.13.8.1 Creating Proxies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 223
2.13.8.2 Creating Proxies of Records with Relationships . . . . . . . . . . . . . . . . . . 224
CONTENTS
ix
2.13.8.3 Merging Proxies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 224
2.14 Constants . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 224
2.15 Webservices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 225
2.15.1 REST Webservices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 225
2.15.1.1 REST Webservice Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 225
2.15.1.2 REST Client . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 227
2.15.2 SOAP Webservices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 228
2.15.2.1 SOAP Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 228
2.15.2.2 Creating SOAP Server from Scratch . . . . . . . . . . . . . . . . . . . . . . . . 229
2.15.2.3 SOAP Client . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 232
2.16 Jasper Reports Integration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 237
2.16.1 Mapping of Parameter Data Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 237
2.16.2 Integrating a Jasper Report with Process Application . . . . . . . . . . . . . . . . . . . . 238
2.16.2.1 Displaying Jasper Report on the Embedded Server . . . . . . . . . . . . . . . . 238
2.16.2.2 Exporting a Jasper Report . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 239
2.16.3 Integrating Process Application with a JasperServer . . . . . . . . . . . . . . . . . . . . . 239
2.16.4 Enabling Expression Language in Jasper Reports . . . . . . . . . . . . . . . . . . . . . . 240
2.17 Monitoring . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 240
2.17.1 Generating and Deploying Business Activity Monitor Example . . . . . . . . . . . . . . . . 242
2.17.1.1 Defining a Default Dashboard . . . . . . . . . . . . . . . . . . . . . . . . . . . 243
2.17.2 Customizing Business Activity Monitor . . . . . . . . . . . . . . . . . . . . . . . . . . . . 244
2.17.2.1 Adding a Custom Widget with a Jasper Report . . . . . . . . . . . . . . . . . . 244
2.17.2.2 Adding a Custom Widget with a Form . . . . . . . . . . . . . . . . . . . . . . . 245
2.17.3 Creating Business Activity Monitor from Scratch . . . . . . . . . . . . . . . . . . . . . . . 247
2.17.4 Configuring the Data Source for Reports . . . . . . . . . . . . . . . . . . . . . . . . . . . 249
2.17.5 Working with the Front End . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 249
2.17.5.1 Creating Dashboards
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 249
2.17.5.2 Displaying Widgets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 252
2.18 Debugging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 254
2.18.1 Debugger Implementation
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 254
x
CONTENTS
2.18.2 Debugger Connection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 255
2.18.2.1 Debugging on the PDS Embedded Server
. . . . . . . . . . . . . . . . . . . . 256
2.18.2.2 Debugging on the Cloud Server . . . . . . . . . . . . . . . . . . . . . . . . . . 258
2.18.2.3 Debugging Custom Process Application Locally . . . . . . . . . . . . . . . . . . 259
2.18.2.4 Debugging on a Remote Server . . . . . . . . . . . . . . . . . . . . . . . . . . 261
2.18.3 Debugging Model Instances . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 263
2.18.3.1 Adding and Removing Breakpoints . . . . . . . . . . . . . . . . . . . . . . . . 264
2.18.3.2 Defining a Breakpoint Condition . . . . . . . . . . . . . . . . . . . . . . . . . . 265
2.18.3.3 Resuming Breakpoints . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 266
2.18.3.4 Enabling and Disabling Breakpoints . . . . . . . . . . . . . . . . . . . . . . . . 266
2.19 Profiling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 266
2.19.1 Enabling Profiling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 266
2.19.2 Performing Model Profiling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 267
2.19.3 Importing and Exporting Profiling Results . . . . . . . . . . . . . . . . . . . . . . . . . . 268
2.20 Debugging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 268
2.20.1 Debugger Implementation
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 269
2.20.2 Debugger Connection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 269
2.20.2.1 Debugging on the PDS Embedded Server
. . . . . . . . . . . . . . . . . . . . 270
2.20.2.2 Debugging on the Cloud Server . . . . . . . . . . . . . . . . . . . . . . . . . . 272
2.20.2.3 Debugging Custom Process Application Locally . . . . . . . . . . . . . . . . . . 273
2.20.2.4 Debugging on a Remote Server . . . . . . . . . . . . . . . . . . . . . . . . . . 275
2.20.3 Debugging Model Instances . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 277
2.20.3.1 Adding and Removing Breakpoints . . . . . . . . . . . . . . . . . . . . . . . . 278
2.20.3.2 Defining a Breakpoint Condition . . . . . . . . . . . . . . . . . . . . . . . . . . 279
2.20.3.3 Resuming Breakpoints . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 280
2.20.3.4 Enabling and Disabling Breakpoints . . . . . . . . . . . . . . . . . . . . . . . . 280
2.21 Profiling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 280
2.21.1 Enabling Profiling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 280
2.21.2 Performing Model Profiling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 281
2.21.3 Importing and Exporting Profiling Results . . . . . . . . . . . . . . . . . . . . . . . . . . 282
CONTENTS
xi
2.22 Resource Sharing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 282
2.22.1 Model and Module Export
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 283
2.22.1.1 Export Configurations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 283
2.22.1.2 Exporting with General Export . . . . . . . . . . . . . . . . . . . . . . . . . . . 283
2.22.1.3 Exporting with GO-BPMN Export . . . . . . . . . . . . . . . . . . . . . . . . . 285
2.22.1.4 Exporting a Module with Maven . . . . . . . . . . . . . . . . . . . . . . . . . . 287
2.22.2 Import . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 288
2.22.2.1 Importing Model Packages to Workspace . . . . . . . . . . . . . . . . . . . . . 289
2.22.2.2 Importing File System Structure . . . . . . . . . . . . . . . . . . . . . . . . . . 290
2.22.3 XPDL Resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 290
2.22.3.1 Exporting to XPDL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 290
2.22.3.2 Importing XPDL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 291
2.22.4 Library
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 292
2.22.4.1 Importing Library to GO-BPMN Projects . . . . . . . . . . . . . . . . . . . . . . 293
2.22.4.2 Exporting Modules as Libraries . . . . . . . . . . . . . . . . . . . . . . . . . . 293
2.22.4.3 Removing Library from a Project . . . . . . . . . . . . . . . . . . . . . . . . . . 294
2.22.5 Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 294
2.22.5.1 Loading File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 294
2.23 Model Presentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 294
3
Execution
295
3.1
Connecting to the PDS Embedded Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 296
3.2
Connecting to an LSPS Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 297
3.3
Model Upload . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 298
3.3.1
Uploading a Module from the Modeling Perspective . . . . . . . . . . . . . . . . . . . . . 298
3.3.2
Uploading a Module from the Management Perspective . . . . . . . . . . . . . . . . . . . 299
3.4
Instantiating a Model from the Management Perspective . . . . . . . . . . . . . . . . . . . . . . . 299
3.5
Instantiating a Model from the Modeling Perspective . . . . . . . . . . . . . . . . . . . . . . . . . 300
3.5.1
Checking Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 300
3.6
Loading and Resetting Database of the LSPS Embedded Server . . . . . . . . . . . . . . . . . . 300
3.7
Resetting Database of the Cloud Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 301
xii
4
CONTENTS
Model Update
4.1
303
Transformation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 304
4.1.1
Transformation Strategies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 306
4.2
Model-Update Processes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 307
4.3
Model Update Logs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 308
4.4
Defining Model Update and Updating Model Instances . . . . . . . . . . . . . . . . . . . . . . . . 309
4.4.1
Creating a Model Update Configuration
4.4.1.1
4.4.2
4.4.3
Copying Model Update Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . 310
Editing Model Update Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 311
4.4.2.1
Displaying Matching Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 312
4.4.2.2
Changing Element Mapping . . . . . . . . . . . . . . . . . . . . . . . . . . . . 313
4.4.2.3
Changing Model Update Settings . . . . . . . . . . . . . . . . . . . . . . . . . 313
4.4.2.4
Defining Transformation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 314
4.4.2.5
Creating a Model Update Process . . . . . . . . . . . . . . . . . . . . . . . . . 317
Updating Model Instances . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 320
4.4.3.1
5
. . . . . . . . . . . . . . . . . . . . . . . . . . . 310
Downloading Model Update Configuration . . . . . . . . . . . . . . . . . . . . . 323
Appendix: User Interface
5.1
Workspace
5.1.1
5.2
325
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 325
Switching Workspace . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 325
Perspective . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 326
5.2.1
Opening Perspectives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 326
5.3
Workbench
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 326
5.4
Views . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 327
5.4.1
Displaying Views, Tabs and Pages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 329
5.4.2
Changing View Position and Detaching Views . . . . . . . . . . . . . . . . . . . . . . . . 330
5.4.3
Using Fast View . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 331
5.5
Editors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 331
5.6
Modeling Tools
5.6.1
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 332
Modeling Perspective . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 332
5.6.1.1
Opening the Modeling Perspective
. . . . . . . . . . . . . . . . . . . . . . . . 333
CONTENTS
xiii
5.6.2
Modeling Views . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 333
5.6.3
GO-BPMN Explorer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 333
5.6.3.1
Filtering in GO-BPMN Explorer . . . . . . . . . . . . . . . . . . . . . . . . . . 335
5.6.4
Outline View
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 336
5.6.5
Properties View . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 336
5.6.6
Problems View . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 337
5.6.7
Error Log View . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 338
5.6.8
Search View
5.6.9
LSPS News View . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 339
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 339
5.6.10 Modeling Editors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 340
5.6.10.1 Form-Like Editors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 340
5.6.10.2 Diagram Editors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 341
5.6.10.3 Export Configuration Editor . . . . . . . . . . . . . . . . . . . . . . . . . . . . 342
5.6.10.4 Form Editor
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 344
Chapter 1
Main Page
When designing your models and related resources for the Living Systems® Process Suite, you will use the integrated development environment called Living Systems® Process Design Suite (PDS), a programming platform
based on Eclipse. The environment comes with the tools for modeling of business process models, their deployment, management, and monitoring.
Note: You can still make use of any capabilities of the underlying Eclipse.
The IDE comes with a local Embedded Server with the LSPS Server to allow you to easily run your Models for
testing purposes: As you design your models, you can test them in the PDS Embedded Server.
The PDS Embedded Server comes with the LSPS Server including the Default Process Application, front-end
application for the user, Management Console, and administration front-end application.
Figure 1.1 LSPS Architecture Schema with PDS on the left
Note: If you install the SDK component in the PDS, you can in addition generate sources of the
Default Process Application, customize it. For instruction on how customize and deploy your own L←SPS Server with these resources refer to the Deployment and Configuration Guide and
for instructions on customizing the Default Process Application, refer to the Customizing the
Process Application.
This guide generally does not contain information on the concepts related to GO-BPMN or the Expression
Language and you might need to refer to the respective reference guides for detailed information.
2
Main Page
1.1
Running Process Design Suite
After you have installed the PDS Cloud or Enterprise edition, run the Process Design Suite:
1. Go to <LSPS_HOME>.
2. Run the lsps-design binary for your platform:
• lsps-design.exe and on Windows with 32-bit architectures
• lsps-design_64.exe on Windows with 64-bit architectures
• Process Design Suite on Mac
• lsps-design on Linux
3. In the Workspace Launcher dialog box, choose a workspace folder and click OK.
If the chosen workspace folder does not exist, it will be created. A workspace is a folder, where the resources
stored during the session are located. Its content is reflected in the workbench.
Figure 1.2 Workspace Launcher dialog
Note: If you are starting PDS in a new workspace, PDS displays the Welcome page with links to
perspectives, documents, and other PDS resources.If all perspectives are closed, the Welcome
command is not available. To activate the Welcome command, open a Process Design Suite
perspective: go to Window > Open Perspective > Other and in the Open Perspective dialog box,
click a Process Design Suite perspective.
1.1 Running Process Design Suite
3
Figure 1.3 Welcome page
You can display it at any point from the main menu Help > Welcome item.
4
Main Page
Chapter 2
Modeling
When designing your models and related resources for the Living Systems® Process Suite, you will do so in the
integrated development environment Living Systems® Process Design Suite (PDS), a programming platform. The
environment comes with the tools for modeling of business process models, their deployment, management, and
monitoring as well as tools for related resources, such as, data type models.
To create a model, first you need to create the model structure: projects with modules. Then you can create
the content of your model in dedicated definition files. When working with definition files, you will create various
elements and their properties.
In your Module, you can create the following content:
• BPMN and GO-BPMN Processes to define execution flows of your processes,
• global variables to store runtime data,
• organization models so you can distribute work to groups of users,
• documents to provide permanent content of the front-end application,
• forms with content of documents and to-dos,
• localization identifiers to have your texts displayed in the required language in the front-end application,
To use your custom entities, you can define your own
• functions,
• task types,
• queries to external database,
• data types,
• persistent data types,
• Constants.
To integrate you models to external system, you can use
• support for web services in your processes.
• support for integration with Jasper reports.
6
Modeling
Your resources will rely on the resources of the Standard Library. Apart from the Standard Library resources,
you can use other out-of-the-box libraries, such as, Monitoring.
To make the development of your content easier and more efficient, you can use the debugger, check performance
using profiler, and improve performance with cache regions.
To make the development of your content easier and more efficient, you can use the debugger, check performance
using profiler, and improve performance with cache regions.
Note that you can import and export the resources.
Once you have created your model and need to present it, you can use the Business Modeling feature.
Typically the following is the workflow of a model:
1. The user creates a model in the Process Design Suite.
2. The model is uploaded to the LSPS Server.
3. An instance of the model is created (the model serves as the definition for its instance).
4. The model instance runs the processes as defined by the model.
During the execution, processes can interact with a database, request data from external systems as well as
human actors.
5. You can interact with the instance with any of the management tools
6. User interacts with your process through to-dos or documents from the Process Application.
2.1
Model Structure
A model is an object that is deployed to the Execution Engine and serves as a blue print for model instances. A
model is not represented by a particular element or item in PDS since comprises an executable module with all its
resources and that including any imported modules. When creating modules, every modules must be created in
a GO-BPMN project. The project is the top-level container for all modules and other artifacts during modeling. It
resembles a common folder. A project is not deployed on runtime and hence does not influence module deployment
or execution.
A workspace may contain multiple GO-BPMN projects. A project contains an arbitrary number of modules (for
details on modules, see GO-BPMN Modeling Language Specification).
Note: Projects are only organization units and are not considered part of a GO-BPMN model.
A GO-BPMN project holds the following:
• modules
• libraries
• model update configurations
• generic files and folders
2.1 Model Structure
7
A project can reference other projects and allow its modules to import modules from the referenced projects (refer
to Referencing Projects). However, it is the modules that hold the definition files with model resources used for
execution, such as, processes, data types, variables, etc.
For further basic information on Models and Modules, refer to the Hello World Guide.
Figure 2.1 GO-BPMN Project Structure
Related links:
• GO-BPMN Projects
• GO-BPMN Modules
• Definitions and Configurations
2.1.1
GO-BPMN Projects
GO-BPMN projects are folders that can hold GO-BPMN Modules. Project content does not depend on other resource unless it references another Project. In such a case, its Modules can import Modules of another Project.
Note that such imports are copies of the original Modules, not references (refer to Referencing Projects).
2.1.1.1
Creating GO-BPMN Projects
A GO-BPMN project is a folder with modules, generic files and folder, and model update and export configurations.
To create a GO-BPMN project, do the following:
1. Click File > New GO-BPMN Project.
Alternatively, open the context menu in the GO-BPMN Explorer and click New > GO-BPMN Project.
2. In the New GO-BPMN Project dialog box, in the Project name text box type the project name.
Note: The GO-BPMN Libraries box displays the libraries and their modules included in the project. The
Standard Library is included by default, however, you may import any library (see
8
Modeling
Figure 2.2 Creating a new GO-BPMN project
1. Click Next.
2. On the Project References page, select the project, which the new project can reference.
3. Click Finish.
2.1.1.2
Closing GO-BPMN Projects
Closing GO-BPMN projects makes projects and their content “invisible” for tools and that including the validation
tool.
To close a project, right-click it in the GO-BPMN Explorer and select Close Project. To open a closed project proceed
analogously.
2.1.1.3
Referencing Projects
If a project references another project, it can use its content (import its Modules). Projects may reference each
other.
To reference a project:
2.1 Model Structure
9
1. In the GO-BPMN Explorer, right-click the project, in which you wish to reference another project and select
Properties.
2. In the left pane of the Properties dialog box, select Project References.
3. In the Project References page, select the projects to be referenced.
Note: When referencing projects, make sure the modules in the project have different names.
You may import modules of the referenced projects into modules of the parent project.
2.1.2
GO-BPMN Modules
GO-BPMN Modules are reusable units that hold definition and configuration files and can represent a Model. Similarly to packages in Java, they serve to organize resource files to logical bundles that can import each other.
2.1.2.1
Creating GO-BPMN Modules
To create a GO-BPMN module:
1. Go to File -> New -> GO-BPMN Module.
You may also use the context menu of the respective GO-BPMN project.
2. In the New GO-BPMN Module dialog box, select the parent GO-BPMN project.
3. In the Module name text box, type the module name.
4. Select or unselect executable module checkbox.
10
Modeling
Figure 2.3 New GO-BPMN Module dialog box
5. Click Finish.
Click Next and define module imports (libraries or modules) if required.
To allow the module to use resources of the Standard Library, import modules of the Standard Library.
2.1.2.2
Specifying Module Properties
When creating a module, its version is set to 1.0 by default and no terminate condition is set.
To specify a module version, terminate condition, and a free-text description:
1. In the GO-BPMN Explorer view, right-click the module.
2. In the context menu, select Properties.
3. In the Properties dialog box, click GO-BPMN in the left part of the dialog box.
4. In the General tab, define the Module properties:
• Module version: a module with a particular version is considered a different module on upload (modules
with different versions can coexist in the server Module repository)
• Executable module: if true, the Module can be instantiated as a Model
Only a module that is executable can become a model instance after uploaded to the LSPS Server.
2.1 Model Structure
11
• Create process log: if selected, the process logs its runtime data into the database
If you disable the setting, runtime data of the Model instance will not include Module data (for example,
no data on process instances nor their diagrams will be available). This setting is intended for production
environments.
Note that the setting can be overridden by the CREATE_PROCESS_LOG setting in the
database.
• Terminate condition: a condition which has to be true throughout the entire life of the model
instance (condition in module imports are ignored)
Figure 2.4 General tab of the Properties dialog box
Alternatively, you can modify the module properties in its Properties view (in GO-BPMN Explorer, select the
module and edit the data in the Properties view).
2.1.2.3
Importing Modules
Module import allows a module to use resources of other modules.
Note that imported executable Modules are instantiated along with their importing executable Module: The system
creates a model instance with 2 or more Module contexts.
To import a module of the same or a referenced project, do the following:
12
Modeling
1. In the GO-BPMN Explorer, right-click the module you wish to import another module (or library) and click
Module Imports.
Figure 2.5 Imports tab with a list of imported modules
2. On the Imports tab, click Add.
3. In the Add New Import dialog box, in the Select a module to import box, select the module to be imported
(expand the tree if necessary).
To add several modules, double-click every module.
4. Click OK.
5. Back in the Properties dialog box, click OK.
To remove a module import, in step 2 select the module and click Remove.
2.1.2.3.1
Viewing Module Dependencies
When referencing projects and importing modules, the relationships between them can become relatively complicated and difficult to follow in the GO-BPMN Explorer. To allow you to view such relationships in a comprehensive
way, the modeling tool provides the Module Dependency View. The view shows a diagram of projects and modules
and their relationships.
To display the view, go to Window > Show View Module Dependency View.
2.1 Model Structure
13
To simplify the module relationships depiction, hide the transitive relationships by clicking the Show Transitive Reduction
and pick the Module you are interested in in the Display dependencies of module drop-down box.
Figure 2.6 Module Dependency View with Transitive Reduction Activated and Deactivated
14
Modeling
Figure 2.7 Module Dependency View with Transitive Reduction Activated and Deactivated
2.1.3
Definitions and Configurations
Definitions and configuration files, or resource files, contain definitions of resources used by the Module, such as,
variables, data types, processes, organization, etc. The resources are always created in a definition or configuration
file of a particular type: global variables can be defined only in a variable definition file; a process can be created
only in a process definition files.
The definitions and configurations have specific extensions and are edited in dedicated PDS editors.
Note: Model update configurations (.muc) and export configurations (.export) exist in GO-BPMN
Projects, not Modules, since .muc requires definition of an old and a new model and export can define
projects and modules.
Some files can contain diagrams, which visualize the content of the file:
Data type Definition (.datatypes) hold data type models with custom data types called Records.
Process Definition (.gobpmn) hold One GO-BPMN or BPMN Process
Organization Definition (.orgmodel) organization model holds (Organization Units and Roles)
For further information on Diagrams as well as the depicted elements, refer to GO-BPMN Modeling
Language.
2.1 Model Structure
2.1.3.1
15
Creating Definitions and Configurations
To create a definition or configuration file, do the following:
1. In the GO-BPMN Explorer view, right-click the respective module or project and click New.
2. Select the desired type of definition file.
Figure 2.8 Creating a definition file
3. Check the location and enter the name of the definition or configuration file.
When creating some definitions, for example, a process definition, the system will prompt you to enter further
properties for the definition file (refer to sections on individual files for information on the properties).
4. Click Finish.
2.1.3.2
Opening Resource Files
By default the system opens a definition or configuration file with the appropriate graphical PDS editor. However,
you can open any file with any internal or external editor.
To open a file with the default editor, double-click the file or any of its children in the GO-BPMN Explorer.
To use a custom editor, right-click the file in GO-BPMN Explorer and select Open With and select the respective
editor. Alternatively, select Other, and in the Editor Selection dialog box, select Internal editors or External programs
and double-click the respective editor.
16
Modeling
For information on how to use native editors, refer to the respective section in editors.
Figure 2.9 Selecting an editor
2.2
Generic Modeling Mechanisms
These are generic mechanisms applicable to the entire environment or all resources:
• Defining expressions
• Defining element properties
• Disabling (commenting out) elements
• Adjusting layout of elements in Diagrams
• Comparing resources
• Using Todo and Task markers
• Defining modeling status of elements
• Validating of the workspace data
• Searching for elements
2.2 Generic Modeling Mechanisms
2.2.1
17
Writing Expressions
Properties of items in Definition and Configuration files, such as, initial values of variables, assignments of process elements, Form elements in the Expression component, etc. are defined as expressions of the Expression
Language. The expressions are evaluated by the Execution Engine at some point on runtime.
Expressions are defined in the Expression Language, which is a typed language of LSPS. For information about the
Language and its constructs, refer to the Expression Language Guide.
When editing expressions, you can use the following features:
• Content Assistant (auto-complete): displays possible values including available data types, language constructs variables, function calls, etc. To display Content Assist, press CTRL + space.
Figure 2.10 Content Assist menu
• Hyperlinking to definitions: opens the definition of the item usage in an expression
Figure 2.11 Link to definition
2.2.1.1
Testing Expressions
You can test expressions in the Expression Evaluator REPL view.
18
Modeling
By default, the view is not displayed: To display it, go to Window > Show View > Other and in the displayed dialog
search for the view.
In the view, you can enter expression and have the system return the resulting value: write an expression and click
Evaluate or press CTRL + Enter (Enter will make a new line in your expression).
Note that you can list the history of expression by pressing the arrow-up key and display auto-completion options
by pressing CTRL + Space.
To erase the context data you created with your expressions in the view, close and re-open it.
If you want to test your expressions in a context of a model instance and use resources of libraries, use the
Expression Evaluator view.
2.2.2
Defining Properties
Every element or item with a semantic execution value, be it a Goal, Task, global variable, a Form component, etc.
needs to define some set of properties related to its execution or behavior. Generally you can edit the properties in
the Properties view, in the editor intended for the element, or in a dedicated popup editor.
Below each property name, you can see the data type of the expression or its return value, for example, the
Properties view below contains the Visible and Root property:
• Visible property accepts a Boolean value: you can insert any expression that will return a Boolean value on
runtime.
• Root property accepts a Collection of TreeItems (the TreeItem type is defined in the ui module) as stated by
(Collection<ui::TreeItem>) below the property name.
2.2 Generic Modeling Mechanisms
19
Figure 2.12 Properties view of a form component
In the case of closures, the label indicates also the input parameters.
Figure 2.13 Condition on a Conditional Intermediate Event element
The Save action is a closure that takes Todo as its first and SavedDocument as its second parameter and returns
an Object value:
Figure 2.14 Editing Save action property
Note that any tab with changes to the property values is marked with an asterisk.
2.2.3
Disabling Elements
The Disabling mechanism serves to exclude elements from validation and execution: you can disable any element,
such as, cache region, variable, process element, etc.
20
Modeling
If a diagram element is disabled, all its diagram views are shown as disabled if applicable. If the disabled diagram
element has any incoming and outgoing Flows or contains any nested modeling elements, all Flows and nested
elements are automatically disabled by the parent.
You can disable elements using their context menu:
• in the editors (on diagrams or in the lists with definitions) or
• in the GO-BPMN Explorer (right-click the element and click Disable)
Note that parameters of elements, such as queries, functions, tasks, etc. can be disabled only in GO-BPMN
Explorer. It is not possible to disable and enable parameters from editors.
Note: If an element is disabled, all its diagram views (representations of the same element in
several diagrams) are shown as disabled (for details on diagrams, see GO-BPMN Modeling Language).
Disabled elements remain visible, however, their representations in both, GO-BPMN Explorer and editors indicate
the disabled status: the views and icons are grayed and crossed out, and a note in the Properties view on element
disabling is displayed.
Figure 2.15 Disabled elements in the Properties view
2.2 Generic Modeling Mechanisms
21
Figure 2.16 Disabled elements in GO-BPMN Explorer
Note: Only modeling elements with a semantic value can be disabled; that is, the disable function
is not available for elements like text annotations, diagrams, or translation identifiers (see GO-BPMN
Modeling Language). On the other hand, you can disable, forms, variables, parameters, etc.
If a disabled element contains other nested modeling elements, the nested elements are disabled as well: to indicate
such a disabling, the label in the Properties view contains the disabled by parent note.
Reflections of disabled elements, such as, the respective record types and functions, must be disabled manually.
Note: Incoming and outgoing flows of a disabled element are disabled by parent automatically.
The GO-BPMN Search allows you to search for disabled elements (see GO-BPMN Search).
22
Modeling
Figure 2.17 Disabling an element in a diagram editor
Figure 2.18 Disabling an element in a form-like editor
2.2.3.1
Defining Formatting of Disabled Elements
You can set the modeling style applied to elements and their views when they are disabled as follows:
2.2 Generic Modeling Mechanisms
23
1. Go to Window > Preferences.
2. In the left part of the Preferences dialog box, expand Process Design Suite > Modeling > Appearance.
3. On the Appearance page on the right, modify the style in the Formatting of Disabled Elements.
2.2.4
Working with Diagrams
Some definition files contain diagrams which visualize the content of the definition file. Such diagrams are edited
with diagram editors specific to the definition type:
• Process diagrams with GO-BPMN and BPMN Processes
• Organization diagrams with organization hierarchies
• Data type diagrams with data type models
The Diagram editors open the diagrams contain the following components:
• canvas with the Diagram elements (The canvas displays the Diagram content; for further information on
Diagrams, refer to GO-BPMN Modeling Language.)
• palette with definition elements Note that you can modify palette size, docking, icon layout, font properties,
and drawers behavior.
Diagram editors are editors for editing of Diagram resources. In these editors, you can edit the content of the
definition file on a canvas typically by dragging-and-dropping elements onto the canvas. The elements are added to
the definition and on the Diagram: Note that an element does not necessarily have to appear in a Diagram: it can
exist in the definition without its Diagram representation. Also one element can appear in multiple Diagram but is
still the same element that exists in the definition only once.
Note: A Diagram is a visualization of elements of a resource file that supports Diagrams and additional Diagram elements. Such a resource file can contain multiple Diagrams and an element from
the resource file can but does not have to be depicted in one or multiple Diagrams. Diagram visualize
their content in oriented graphs of element views, that is, pictures representing the element and its
relationships. Diagrams can contain the following:
• views which are graphical representations of elements from the definition; for example, a Diagram
in an organization definition can contain one or multiple views of any Role or Organization Unit in
the organization definition;
• diagram elements such as annotations; such elements do not have any semantic value for execution but serve to provide information to the user when they view the diagrams. For more
information on Diagram types, elements, and content, refer to GO-BPMN Modeling Language
Specification.
When you create a resource that supports Diagrams, the system automatically creates a Diagram in the resource
file and displays it in the respective diagram editor. Note that you can create other Diagrams in the definition file.
Any such file can contain an arbitrary number of Diagrams or even contain no Diagrams.
You can apply the following global settings for your diagram editors:
• Settings on displayed elements:
24
Modeling
– Show Diagram Annotations: if unselected, all Annotation elements are hidden (that is Annotations,
Associations, hyperlinks, and diagram frames).
– Show Validation Errors/Warnings: if unselected, all error and warning markers are hidden.
– Show Modeling Statuses: if unselected, the properties applied on the diagram element due to their
modeling status are cancelled.
– Show Monitoring: if unselected, monitoring markers on elements with monitoring expressions are hidden.
Monitoring expressions hold expressions that store monitoring data. Such data can be then used in
monitoring applications.
– Show Tooltip: if unselected, tooltips with descriptions of elements are not displayed on mouse hover.
– Show Translations: if unselected, the form editor displays the localization identifier call instead of the
default value of the identifier.
Figure 2.19 Menu with Global Diagram Editor Settings
• General settings such as line style, task visualization, etc. Go to Windows > Preferences, then Process
Design Suite > Modeling > Appearance.
2.2 Generic Modeling Mechanisms
25
Figure 2.20 General settings
2.2.4.1
Creating a Diagram
After you have created a definition, which may contain diagrams (process, organization, or data type definition, or a
process in the model update configuration), the system creates a diagram in the file and opens it in the respective
diagram editor. However, you can decide to create multiple diagrams in one file with different element views. To
create a new diagram, do the following:
1. In the GO-BPMN Explorer, right-click the resource or element.
2. Select New -> Diagram.
2.2.4.2
Inserting Element Views
Any view of an element with semantic value that you insert into a Diagram are automatically created in the definition
file, for example, if you insert a Role view into an Organization Diagram, the system automatically creates the Role
element in the definition file.
To create a new element and insert its view to a diagram:
1. Click the element on the palette.
26
Modeling
2. Click the area on the canvas, where you want to place the element view. If further specification of the element
is necessary, a dialog box with the possible values appears.
To insert an element view without using the Palette, right-click empty space in the canvas and select the element
from the context menu.
Figure 2.21 Inserting a new element through context menus
For quick inserting of new elements onto the canvas, use the quicklinker:
1. Select a diagram element.
2. Drag the quick linker symbol to the target icon, or to an area, where you want to create the target element
view; and in the context menu, select the target element.
Figure 2.22 Quicklinker
You can insert an element view in between two elements connected with a flow by placing the view on the Flow
element: the Flow will be split in two Flows with the element in between.
2.2 Generic Modeling Mechanisms
2.2.4.3
27
Aligning Element Views
To align element view in a diagram editor according one of the elements, do the following:
1. Select the elements on the canvas: Either drag a select box around the elements or use the Ctrl + right-click.
• The align is performed according to the primary element. The primary element is the element in the
selection with white border points by default. To mark another element as the primary element of the
selection, press and hold the Shift key and right-click the element.
Figure 2.23 Primary element view in a selection
2. Click the Alignment (
) button on the editor toolbar and pick the align type:
• Align Left aligns all selected elements according to the left border of the primary element.
• Align Center aligns all selected elements vertically according to the center of the primary element.
• Align Right aligns all selected elements according to the right border of the primary element.
• Align Top aligns all selected elements according to the top border of the primary element.
• Align Middle aligns all selected elements horizontally according to the top border of the primary element.
• Align Bottom aligns all selected elements according to the bottom border of the primary element.
2.2.4.4
Matching Element Views Size
To match sizes of several diagram elements to the size of one element, do the following:
1. Select the elements on the canvas
28
Modeling
2. Select the primary element: it is the properties, that is, width and height, of this elements that are applied
to the other selected elements. The primary element is the selected element with white border points. To
mark another element as the primary element of the selection, press and hold the Shift key and right-click the
element.
3. On the main toolbar, click the Size (
) button, and select the resizing strategy:
• Match Width to resize the elements' width according to the primary element
• Match Height to resize the elements' height according to the primary element. To restore the original
size of a diagram element, right-click it and select Auto Resize.
2.2.4.5
Spreading Diagram Element Views
When spreading elements, the selected element are rearranged in such a way that the space they occupy remains
unchanged while the "gaps" between the elements become equal.
To spread diagram elements in a diagram editor evenly, do the following:
1. Select the desired elements on the canvas: Either drag a select box around the elements or use the Ctrl +
right-click.
2. Click the Spreading (
) button on the editor toolbar and pick the spreading strategy:
• Horizontal Spread Evenly spreads the elements horizontally.
• Vertical Spread Evenly spreads the elements vertically.
2.2.4.6
Locating Element from a Diagram
To locate an element in the GO-BPMN Explorer or Properties view from a Diagram:
1. In a diagram editor, right-click the diagram element. Right-click empty space on the canvas to locate a
diagram.
2. In the context menu, select Show In > GO-BPMN Explorer or Properties.
Figure 2.24 Locating Record field in GO-BPMN Explorer
2.2 Generic Modeling Mechanisms
2.2.4.7
29
Changing Process Element Type
To change the type of a Process diagram element, do the following:
1. Right-click the element icon.
2. In the context menu, click Change To and select the required element type. When changing the task type of
a task to another task type, select Change Type. Note that original parameter values will be reused and, if
incompatible, the system will detect an error. You can perform task parameter clean-up. If changing other
element types, the original parameters are dropped.
2.2.4.8
Deleting Elements from Diagrams
When deleting an element view in a diagram, you can either delete the element with all its view or delete only the
view and preserve the respective element.
Note: On execution, process elements with no diagram view (icon representing the element) cannot
have a breakpoint.
To remove an element or its view:
1. In the respective diagram (opened in the respective diagram editor), locate the desired element view.
2. Right-click the element view:
• Click Delete From Diagram to delete only the element view from the diagram;
• Click Delete Element to delete the element (as a consequence all its diagram views are removed).
2.2.4.9
Snapping to Grid
The grid provides helping lines and allows you to align element views on diagrams automatically.
To set and display and set the grid, do the following:
1. On the main menu, go to Window > Preferences.
2. In the Preferences dialog box, expand Process Design Suite > Modeling, and click Alignment.
3. On the Alignment page, set the grid properties:
• Snap to grid: automatically aligns diagram elements to the grid;
• Show grid: displays the grid;
• define the grid size in pixels;
• select Snap to geometry to snap element to the grid guidelines when moved
When moving a diagram view or element, guidelines indicate a border (top, bottom, left, or right) of
another diagram icon to help to define the required position.
4. Click OK.
30
Modeling
2.2.4.10
Customizing the Palette
You have activated a diagram editor.
1. Right-click anywhere on the palette (not on its title bar) and select Settings.
Figure 2.25 Customizing Palette
2. In the dialog box, define the palette properties.
3. Click OK to apply the settings.
2.2.4.11
Displaying Page Borders
To display page borders in diagrams, do the following:
1. Click Window > Preferences.
2. In the Preferences dialog box, expand Process Design Suite.
3. In the left pane, click Modeling.
2.2 Generic Modeling Mechanisms
31
4. Under Show Page Borders on Diagram, select the respective option.
Figure 2.26 Setting the number of diagram frames nesting
2.2.4.12
2.2.4.12.1
Diagram Elements
Diagram Frames
Diagram frames are diagram elements, which allow you to visualize another Diagram. They have no semantic value
and are read-only. Whenever the content of the diagram referenced by a frame changes, the content of the frame
changes respectively.
Tip: Use (directed) associations and annotations to establish logical links between an element shown
in a diagram frame (or the entire diagram frame) and other elements in the diagram.
It is not possible to insert a diagram frame of a resource of a different type (for example, you cannot insert a goal
diagram frame to an organization diagram). A diagram frame cannot reference itself.
Note that you can restring the level of allowed frame settings in Window > Preferences and then Process Design
Suite > Modeling.
32
Modeling
2.2.4.12.2
Hyperlinks
Hyperlinks are diagram elements used to facilitate navigation in diagrams (they provide direct links to a location/resource/element).
Note: If a hyperlink refers to a disabled entity, validation reports a warning.
When a hyperlink is clicked, the linked entity is displayed in the respective editor. There are four types of hyperlinks:
• Diagram hyperlink: link to another diagram;
• URL hyperlink: link to a URL;
• Element hyperlink: link to an element of the project;
• Resource hyperlink: link to a module resource of the project.
∗∗Note:∗∗Hyperlinks cannot be used in model update processes (see Creating Model Update Process,
for information on concepts see GO-BPMN Modeling Language Specification).
2.2.4.12.2.1
Inserting Hyperlinks
To insert a hyperlink, do the following:
1. Open the respective diagram in the diagram editor.
2. On the palette, click the respective hyperlink button.
3. Click the canvas area, where you wish to place the hyperlink.
Alternatively right-click anywhere on the canvas, and select New and the desired hyperlink or drag the respective
element onto the canvas (if applicable, select Create Hyperlink in the displayed menu).
2.2.4.12.2.2
Switching Iconic and Decorative Notation
Some diagram views can be displayed in two notation variants:
• Iconic notation is compact and used for element notation by default
• Decorative notation is descriptive and contains further details about the particular element.
Notation variants (iconic and decorative) are available for the following element views:
• goals;
• plans;
• roles;
• organization units.
To change notation of a diagram element, do the following:
2.2 Generic Modeling Mechanisms
33
1. Open the diagram with the desired element view.
2. Right-click the element view and select Notation and the type of notation (Iconic/Decorative).
When applying decorative notation, you may chose the details, which should be shown: in the context menu of the
element icon select Compartments and select the compartments to be displayed.
Figure 2.27 Goal hierarchy with views in decorative and iconic notation
2.2.4.12.2.3
Hiding and Displaying Compartments of Diagram Elements
You can hide the task type compartments of the task elements, inherited fields in a record.
To hide or display the compartments on a diagram element, do the following:
1. Right-click the element on the canvas.
2. In the context menu, select Compartment and select the compartment to hide or show.
Note that the element settings can be overridden by global format settings (Changing Default Compartment Visibility).
34
Modeling
2.2.4.12.2.4
Changing Line Style
The line style defines the behavior of line elements and that their bending.
The following line styles are available:
• Direct: No bend points are allowed (only straight line are used).
Figure 2.28 Diagram with direct line style
• Tree: Lines are bent only in the right angle.
Figure 2.29 Diagram with tree line style
2.2 Generic Modeling Mechanisms
35
• Custom: Lines are direct with additional bend points and the possibility to create new bendpoints
Figure 2.30 Diagram with custom line style
To change the style of line, do the following:
1. Select the line element in the diagram.
2. In the Properties view, click the Appearance tab.
3. In the Line style drop-down menu, select the style to apply on the line element.
2.2.4.13
Formatting Settings
Formatting settings define how the diagram elements are depicted and organized in the diagram to allow you to
create well-organized and comprehensible diagrams.
Every diagram element defines a set of its formatting properties, such as its fill color, outline color, text font, displayed
compartments etc. (refer to Defining Custom Format of Elements and Hiding Compartments of Diagram Elements).
Apart for the element formatting properties, diagram editors define global formatting settings, which override the
local settings and define additional formatting properties.
2.2.4.13.1
Custom Format
You can define the formatting of every diagram element.
Note that custom formatting is overridden by the monochrome and modeling status format.
To customize the formatting of a diagram element, do the following:
1. Select the element on the canvas.
2. In the Properties view, display the Format tab.
3. On the Format tab, select the formatting attribute and choose the formatting property.
Alternatively, use format buttons available in the editor main toolbar.
36
Modeling
2.2.4.13.2
Applying Custom Format Style
To get and apply a custom format style on an element view, do the following:
1. On the canvas, select the element with the format you wish to apply to another element.
2. In the main toolbar, click the Get Style button (
).
3. On the canvas, select the element to apply the format style to.
4. In the main toolbar, click the Apply Style (
) button.
The format style is applied to the element. The custom format style may not be visible since custom formatting is
overridden by the monochrome and status formatting style.
2.2.4.13.3
Activating Monochrome Style
Monochrome style is a two-color style applied to diagram elements. By default the style is set to black-and-white.
It overrides any custom style (if applied to diagram elements with custom color style, the elements loose their
coloring). However, it does not influence the status coloring.
To activate or deactivate and modify the monochrome style, do the following:
1. Go to Window > Preferences.
2. In the left part of the Preferences dialog box, expand Process Design Suite > Modeling > Appearance.
3. On the Appearance page on the right, select or unselect Use monochrome color style in Diagrams.
Figure 2.31 Appearance page of the Preferences dialog box
2.2 Generic Modeling Mechanisms
37
Optionally, customize the colors used by the style in the Monochrome Style Details area below (available if the Use
monochrome style in diagrams checkbox is selected).
2.2.4.13.4
Activating Gradient Style
To deactivate or activate the gradient style of diagram elements:
1. Go to Window > Preferences.
2. In the left part of the Preferences dialog box, expand Process Design Suite > Modeling > Appearance.
3. On the Appearance page on the right, select or unselect Use gradient style in diagrams.
Figure 2.32 Appearance page of the Preferences dialog box
2.2.4.13.5
Activating Transparency on Text Annotations
To deactivate or activate and define transparency property of Text Annotations:
1. Go to Window > Preferences.
2. In the left part of the Preferences dialog box, expand Process Design Suite > Modeling > Appearance.
3. On the Appearance page on the right, select or unselect Text annotation transparency (alpha 0-255) and
enter a valid value (255 stands for no transparency).
4. Click Apply.
38
Modeling
2.2.4.13.6
Changing Primary Element Color
To change the color of the primary element, do the following:
1. Go to Window > Preferences.
2. In the left part of the Preferences dialog box, expand Process Design Suite > Modeling > Appearance.
3. On the Appearance page on the right, click the Selection handle color box and select a color.
2.2.4.13.7
Changing Default Line Style
The line style defines the style how the line elements bent.
To change the default line style, do the following:
1. Go to Window > Preferences.
2. In the left part of the Preferences dialog box, expand Process Design Suite > Modeling > Appearance.
3. On the Appearance page on the right, select the default line style in the drop-down menu. You can define
enable or disable the line rounding using the checkbox below.
4. Click Apply.
Figure 2.33 Select with the Primary Element in custom color
Note that the default line style is applied only on new line elements. Style of existing line elements remains unchanged.
2.2 Generic Modeling Mechanisms
2.2.4.13.8
39
Changing Formatting of Element Views
You can define the formatting of every diagram element view. Such custom formatting is however overridden by the
monochrome and modeling status format.
To customize the formatting of a diagram element, do the following:
1. Select the element on the canvas.
2. In the Properties view, display the Format tab.
3. On the Format tab, select the formatting attribute and choose the formatting property. Alternatively, use the
format buttons available in the editor main toolbar.
2.2.4.14
Diagram Printing
When printing Diagrams, the system follows the global page setup by default. However, you can override its setting
in a local setup defined per Diagram.
You can export and import local page setups so you can share them with other users and print your Diagrams with
the same settings.
2.2.4.14.1
Defining Global Page Setup
The setting is applied on every diagram printing and PDF export unless the local page setup is applied.
To define the global page setup, go to File > Page Setup.
Figure 2.34 Page setup
40
Modeling
2.2.4.14.2
Defining Local Printing Setup
To define printing setup for a Diagram, set the printing properties in the Printing tab of the Properties view. Mind
that this setting is applied whenever the diagram is included in a PDF or image export and you need to disable the
local page setup to re-apply the global page setup on the diagram.
2.2.4.14.3
Defining Header and Footer
To define header or footer in a global or local page setup, do the following:
1. Go to the respective page setup (for global page setup: File > Page Setup; for local page setup: Printing tab
of the Properties view).
2. Click the Manage button next to the Page header/Page footer drop-down box.
3. In the displayed dialog, click the respective tab label (Page Headers or Page Footers).
• To add a new definition, click the Add button.
• To edit an existing definition, select the definition and click Edit.
4. In the displayed dialog (Page Header or Page Footer) define:
• Name of the definition
• Font to be used (click Change to define font settings)
• Number of lines
• Content of the left, middle, and right part of the header or footer in the areas below: Click the respective
button above, to enter variable data.
Figure 2.35 Page header setup
2.2 Generic Modeling Mechanisms
2.2.4.14.4
41
Exporting and Importing Page Setup
To export or import the global page setup, do the following:
1. Go to File > Page Setup.
2. In the Page Setup dialog box, click the Export or Import button.
Figure 2.36 Exporting/Importing page setup
3. In the displayed dialog box, define the location and name of the export/import file.
2.2.4.14.5
Exporting Diagrams as Images
The Process Design Suite allows exporting diagrams as images, and groups of diagrams as a structured PDF
document.
A diagram can be exported into the PDF format and as an SVG, PNG, JPG, or BMP image.
Important: When exporting a diagram to SVG, make sure the diagram font is installed on your system.
The default font used in diagrams is Arial, which is installed on MS Windows by default. Hence this
applies especially to users of other operating systems.
Alternatively you can change the diagram font for PDS: go to Window > Preferences and in the Preferences dialog, go to General > Appearance > Colors and Fonts, and under the Process Design Suite,
select Diagram Font and click Edit.
Note that the exported SVG diagram has the clip attribute on the <svg:text> element. The attribute
might cause the text to be cut off. Delete the attribute in your SVG to resolve the issue.
42
Modeling
2.2.4.14.6
Printing Diagram Element Selection
You have activated the respective diagram in its editor and selected the element icons in the editor. Note:
When printing a selection of diagram elements, the global page setup is applied, see Page Setup).
To print a selection of diagram elements:
1. Go to File > Print.
2. Select the Print the selected elements option.
Figure 2.37 Print Diagrams dialog with the Print the selected elements selectedCaption text
3. Check the print preview on the right.
2.2.4.14.6.1
Printing Multiple Diagrams
Note: The page setup applied to individual diagrams is applied also on its printing (that is, the global page setup
is applied by default; if a diagram defines a local page setup, for printing of this diagram the local page setup is
applied, see Page Setup).
To print several diagrams from a project or Module, do the following:
2.2 Generic Modeling Mechanisms
2.2.4.15
43
Aligning Diagram Elements
To align elements in a diagram editor according one of the elements, do the following:
1. Select the desired elements on the canvas: Either drag a select box around the elements or use the Ctrl +
right-click.
The align is performed according to the primary element. The primary element is the selected element with
white border points. To mark another element as the primary element of the selection, press and hold the
Shift key and right-click the element.
Figure 2.38 A plan selected as the primary element
2. Click the Alignment (
2.2.4.16
) button on the editor toolbar and pick the align strategy.
Applying Automatic Layout in Diagrams
The automatic formatting of diagram views, does the following:
• Arranges elements in hierarchy levels
• Resolves any overlapping elements
To automatically adjust the element layout on your diagram, right-click into the diagram canvas and select Layout.
44
Modeling
Figure 2.39 Performing autolayout
Auto layout automatically adjusts position of the diagram elements in a vertical manner.
Figure 2.40 Autolayout process diagram
Note: If an element displayed in a process diagram contains a boundary event, the layout feature is
disabled.
2.2 Generic Modeling Mechanisms
45
If you want to adjust the layout of the elements in a Diagram whenever the diagram is opened, do the following:
1. Open the definition file for editing (double-click it in the GO-BPMN Explorer)
2. Select the Diagram in the Outline view.
3. On the Detail tab in the Properties view of the diagram, select Auto layout.
4. Close the editor with the diagram and open it anew.
The diagram elements will be layout automatically anew whenever the diagram is opened: Note that the editor with
the diagram will be marked as dirty (with the asterisk ∗ sign).
Figure 2.41 Goal diagram opened after Auto-layout was selected
2.2.5
Comparing Resources
You can compare the resources you create in PDS with a dedicated Comparing tool that visualizes the detected
differences and allows you to merge the differences among the compared resources. It detects changes with
semantic significance, such as, a removed task, as well as other changes, such as changes in element layout, size,
etc.
You can compare two or three resources of the same type, and that, projects, modules, or configurations and
definitions.
46
Modeling
2.2.5.1
Comparing Two Resources
To compare two resources, do the following:
1. Select the resources (Ctrl + mouse click to select) in the GO-BPMN Explorer.
2. Right-click one of the selected resources and click Compare With > Each Other.
When comparing Modules or projects, you will see the files with detected differences. To display the differences on the files, click the file: in the displayed diff, use the buttons in the toolbar to navigate through the
differences.
Figure 2.42 Comparing goal-based Processes
3. To apply a difference on either resource, right-click the difference and select the required action from the
context menu.
2.2 Generic Modeling Mechanisms
47
Figure 2.43 Resolving difference
To switch from the LSPS Compare to a text compare, click the arrow on top of the comparison table and click Text
Compare.
2.2.5.2
Comparing Three Resources
To compare three resources, do the following:
1. In the GO-BPMN Explorer, select three resources of the same type.
2. Right-click one of the selected resources, and select Compare With > Each Other.
3. In the Select Common Ancestor dialog box, select the common ancestor, the original resource, and click OK.
When comparing three resources, the following takes place:
• The ancestor resource and the first modification are compared.
• The ancestor and the second modification are compared.
48
Modeling
• Results of both previous comparisons are compared and visualized in the table of the Comparison
Editor.
Figure 2.44 Defining the ancestor resource
When comparing Modules or projects, you will see the files with detected differences. To display the
differences on the files, click the file: in the displayed diff, use the buttons in the toolbar to navigate
through the differences.
Note that changes that are not in either of the resources are marked with
marked with
while identical changes are
.
4. Merge required changes into the respective modifications if applicable (You cannot merge a difference into
the ancestor resource).
Figure 2.45 Comparing three resources
To switch from the LSPS Compare to a text compare, click the arrow on top of the comparison table and click
Text Compare.
2.2 Generic Modeling Mechanisms
Marker
49
Description
The left modification adds an element to the ancestor. This change is not in conflict with those
ones in the right modification.
The left modification removes an element from the ancestor. This change is not in conflict with
those ones in the right modification.
The left modification updates an element of the ancestor. This change is not in conflict with
those ones in the right modification.
The left modification adds an element to the ancestor. However, this change is in conflict with
those ones in the right modification.
The left modification removes an element from the ancestor. However, this change is in conflict
with those ones in the right modification.
The left modification updates an element of the ancestor. However, this change is in conflict
with those ones in the right modification.
The right modification adds an element to the ancestor. This change is not in conflict with those
ones in the left modification.
The right modification removes an element from the ancestor. This change is not in conflict with
those ones in the left modification.
The right modification updates an element of the ancestor. This change is not in conflict with
those ones in the left modification.
The right modification adds an element to the ancestor. However, this change is in conflict with
those ones in the left modification.
The right modification removes an element from the ancestor. However, this change is in conflict
with those ones in the left modification.
The right modification updates an element of the ancestor. However, this change is in conflict
with those ones in the left modification.
2.2.5.3
Comparing Version-Controlled Resources
The comparing procedure can vary depending on your version control system. Generally, do the following to compare your local changes to the committed resource version:
1. In the GO-BPMN Explorer, select the resource.
50
Modeling
2. Click Compare With -> Latest from Repository.
3. Synchronize your changes with the Repository if applicable: Right-click the resource and select Team ->
Synchronize with Repository.
2.2.5.3.1
Merging
You can merge the differences in diagram resources just like you would when comparing resources in the Comparison Editor: You may accept or reject the detected differences from any of the resources (baseline or modifications)
to create the required merge result. The Comparison Editor is activated and contains comparison results automatically.
A yellow indicator appears on the side when a difference has been merged into one of the resources.
2.2.6
Todo and Task Markers
In PDS, you can track as well as incomplete expressions and incomplete modeling elements: To track incomplete
expressions, use the //TODO marker: add the marker to the expression that needs to be completed. You can
parametrize the marker in the form /∗TODO <TEXT>∗/. The <TEXT> is kept as the marker's description.
To track incomplete elements, such as, global variables, Process elements, etc., apply to the elements a modeling
status with a priority: The priority is interpreted as a task marker.
You can view all such Markers in the Eclipse Tasks view: To open the view, go to Windows > Show View > Tasks.
Figure 2.46 The TODO Marker
2.2 Generic Modeling Mechanisms
51
If elements in a modeling status with a priority are not displayed, check the filtering of the view: in the Task view,
click the View Menu (
required priority.
) button and select Configure Contents. Make sure the filtering is set correctly and set the
Figure 2.47 Setting contents properties for todo tasks
2.2.7
Modeling Status
Modeling Status is a property set for a Module element, such as, a Process, variable, constraint, organization role,
etc. that serves to clearly annotate an element during the designing phase, for example, as a draft element, or an
element that is a probably not required without influencing the semantics of the element.
A modeling status definition must define its name and can define presentation properties of elements when they will
be in that modeling status.
Task priority of a modeling status is implicitly set to Todo so elements with such a modeling status can be displayed
in the Tasks view (refer to Todo and Task Markers and Modeling Status).
2.2.7.1
Setting Modeling Status
Modeling status of an element is a special formatting indicating the stage of its design development.
To specify modeling status of a visual element, do the following:
52
Modeling
1. Activate the respective element Properties view (for example, double-click the desired element in the GO-←BPMN Explorer).
2. In the Properties view, on the Detail tab in the Status drop-down box:
• select one of the available statuses;
• type a custom status name.
Tip: Alternatively, select one or several icon in the diagram or in the GO-BPMN Explorer and
use the Status drop-down box on the toolbar or their context menu.
Figure 2.48 Elements with various modeling statuses
The modeling status and the respective formatting is applied to all element views in diagrams and the element name
in GO-BPMN Explorer.
To specify modeling status on a text element, such as, a text function definition and methods, add the \@Status
(<STATUS_NAME>), for example, @Status (Agreed).
2.2.7.2
Defining Modeling Status
To define, edit, or remove a modeling status in your workspace, do the following:
1. Go to Window -> Preferences.
2. In the Preference dialog, go to Process Design Suite -> Modeling -> Modeling Status.
3. Perform the required actions.
Note that modeling statuses can be redefined on individual projects.
2.2.7.3
Defining Modeling Status for a Project
To define, edit, or remove a modeling status in a GO-BPMN project, do the following:
1. In the GO-BPMN Explorer, right-click your project and select Properties.
2. In the left pane of the Properties dialog, click PDS Modeling Status.
3. Select the Enable project specific settings option.
4. Perform the required actions on modeling statuses.
2.2 Generic Modeling Mechanisms
2.2.7.4
53
Exporting and Importing Status Definitions
To export or import modeling status definitions:
1. Click Window > Preferences.
2. In the left pane of the Preferences dialog box, expand Process Design Suite and Modeling.
3. Click Modeling Status.
4. Click the Export/Import button on the right.
5. Specify the location and the file name.
6. Click Save/Open.
7. In the Preferences dialog box, click Apply/OK.
2.2.7.5
Disabling Modeling Statuses
You can disable the properties applied to the presentation of elements by a modeling status in the Diagrams as well
as in views, such as, Outline view.
Figure 2.49 Modeling status applied on the element visible in diagrams and in views
To hide the properties, do the following:
• in all diagrams, click the Show Diagram Items
unselect the Show Modeling Statuses item.
button in the main toolbar and in the context menu,
• in all views, go to Window -> Preferences and then Process Design Suite -> Modeling -> Modeling
Status and unselect //Show modeling statuses in views//.
54
Modeling
2.2.8
Workspace Validation
Workspace Validation is a mechanism checking the language and modeling correctness of the saved workspace
data.
A workspace resource can be validated:
• automatically;
• manually.
Modules can be uploaded to the server only if valid: Validation is performed automatically before a Module is
uploaded.
Note: Non-Executable Processes and contents of Non-Main Pools are never validated.
2.2.8.1
Problem Severity
A problem detected by validation may be classified as an error, warning or info each having its own impact on the
overall validity.
Problem severity is indicated by markers:
• Errors
are fatal mistakes. A module with errors cannot be deployed.
are issues that may affect execution and cause undesired behavior but are not real errors (for
• Warnings
example, a missing value of a parameter, which is interpreted automatically as null).
are notifications of non-standard situations, which influence neither the validity nor further deploy• Infos
ment. Infos occur, for example, if a modeling element is present in the process definition, but does not appear
in any Diagram.
Note: Problem markers appear on all visualizations of the element and all its parent modeling elements
recursively.
2.2.8.2
Configuring Workspace Validation
To configure validations for your workspace, do the following:
1. Click Window > Preferences.
2. In the Preferences dialog box in the left pane, expand Process Design Suite.
2.2 Generic Modeling Mechanisms
55
3. Expand Modeling and click Validation.
Figure 2.50 Validation page with predefined settings
4. Click the respective severity level for the described problem and provide the maximum length of a database
object.
5. Click Apply or OK.
Note that you can override the workspace validation settings on individual Projects.
2.2.8.3
Configuring Project Validation
To configure validations for a GO-BPMN Project, do the following:
1. In the GO-BPMN Explorer, right-click the project and click Properties.
2. In the Properties dialog box, click PDS Validation.
3. On the right, select Ennable project specific settings and set the options.
4. Click OK.
56
Modeling
2.2.8.4
Automatic Validation
When the automatic validation feature is activated, workspace resources are validated automatically (validation
takes place where a resource is saved) and the respective problem markers appear next to elements with the
problems and on all their parents (the problems are distributed upwards).
To turn on automatic validation, select Project Build Automatically: Automatic validation is turned on when
the check sign
command.
is displayed next to the Build Automatically command. To turn off automatic validation, clear the
To analyze detected problems, use the Problems view (refer to Problems View).
2.2.8.5
Manual Validation
To validate your resource manually, do the following:
1. In the GO-BPMN Explorer view, right-click the project, module, or resource.
2. Click Validate.
2.2.8.6
Validating Old Modules
Imported GO-BPMN Modules created in older versions of the Process Design Suite may not be validated automatically. To enable validation of older modules:
1. Click Project -> Configure GO-BPMN Validator.
2. Click OK.
Any old GO-BPMN modules in the workspace are added to the validation scope.
2.2.8.7
Hiding Validation Markers
To hide problem markers in a diagram editor (markers remain visible in the GO-BPMN Explorer and other views):
1. Click Show Diagram Items (
) button on the main toolbar.
The button is available only when a diagram editor is focused.
2. Unselect Show Validation Errors/Warnings.
2.2.9
Search
You can search in your workspace using any of the available Eclipse searches; however, to search the GO-BPMN
Project content, we recommend the following:
• To search for elements or strings, use the GO-BPMN Search;
• To search for usages of a definition, use the usage search of an elements.
• To search for Tasks that influence a Goal condition, search for dependent Tasks of the Goal.
• To search for calls and acquire entire call hierarchies, that is, the entire chains of the calls, use the call
hierarchy search.
2.2 Generic Modeling Mechanisms
2.2.9.1
57
Searching for GO-BPMN Entities and their Usage
GO-BPMN search is the generic LSPS search and allows you to search for entities based on their name, type, or
status.
To define and perform such a search, do the following:
1. Go to Search> GO-BPMN.
2. In the search dialog, define the search criteria
• Search string: string to search for in elements
– Case sensitive: upper and lower cases are distinguished
– Wildcard search: wildcards are allowed (∗, ?)
• Type of search
– Element type search: returns elements meeting the defined criteria (see Element Type Search)
– Full-text search: returns any entities containing the defined string
• Scope
– Workspace: search is performed within the active workspace
– Selected resources: search is performed within the defined resources (projects, modules, libraries)
• Element Type Search
The results will be displayed in the Search view.
58
Modeling
2.2.9.2
Searching for Elements
The Open Element feature is a search that locates any element containing the provided string.
To search for an element and open it in its native editor:
1. Go to Navigate > Open Element
2. In the Open Element dialog, type the element name or its part.
3. In the area with search results below, double-click the element you wish to navigate to.
Figure 2.51 The Open Element dialog with search results
2.2.9.3
Searching for Element Usages
To search for usages of GO-BPMN elements, such as, functions, variables, records, record fields, process elements, etc., right-click the definition or declaration in its editor or in the Outline view and in the context menu, go to
Search For and select Usages or the relevant occurrences; on variables, you can search for read or write accesses
separately.
2.2 Generic Modeling Mechanisms
2.2.9.4
59
Searching for Dependent Tasks
Dependent Tasks searches for Tasks, which influence goal conditions (pre-condition or deactivate condition of
achieve goals; maintain condition of maintain goals);
To search for tasks, which influence a goal condition, do the following:
1. In the GO-BPMN Explorer or in a goal diagram, locate the goal.
2. Right-click the goal, and click Search For > Dependent Tasks.
3. In the Search for Dependent Tasks dialog box, specify the search scope, and click Search.
Search results are displayed in the Search view.
2.2.9.5
Searching for Call Hierarchies
To search and open the call hierarchies over a definition, right-click the definition in the editor or the Outline view
and click Open Call Hierarchy.
Figure 2.52 Opening call hierarchy of a function definition
2.2.9.6
Searching for Unused Elements
To search for unused elements, go to Search > Find Unused Elements.
Note: The search does not return unused methods.
60
Modeling
2.3
Processes
A Process Definition file holds one BPMN or GO-BPMN Process. You can create multiple such files in a Module.
Since a process represents a namespace, it can define its local variables and parameters. For further information
on Processes and their elements, refer to GO-BPMN Modeling Language Guide.
2.3.1
Creating a Process
To create a Process, do the following:
1. In GO-BPMN Explorer, right-click the Module and go to New > Process Definition or double-click an existing
definition.
2. In the dialog box, define the properties or the Process:
• Container: parent Module
• Type: whether the Process is goal based or a standard BPMN process without the GO-BPMN extension
• Visibility: visibility when the parent Module is imported When Private, the Process content will not be
accessible from importing Modules.
• Executable: Process are instantiated as part of a Model instance and can be used as a Sub-Process
or as the Activity parameter of the Execute task
The flag serves to disable instantiation of processes that serve for documentation purposes and are not
intended for execution.
• Instantiate Automatically: if selected, the Process is instantiated when its parent Model is instantiated
and that even if it is imported in a non-executable Module.
3. Define the workflow of the Process in Modeler on the displayed tab with the Diagram: right-click into the canvas and select the element to insert. You can then create further elements with the quick-linker. Alternatively,
click the element in the palette on the right and click on the canvas to place the element on the diagram and
create it in the definition file.
2.3 Processes
61
Figure 2.53 Creating Process workflow
2.3.2
Defining Element Labels
To allow the modeler to display the same name on multiple elements in a process diagram, all process elements
apart from the Annotation elements can define a Label property: if the label contains a value, it is displayed on the
diagram instead of the name of the element. It is intended for purely presentation purposes and does not have to
be unique in the namespace unlike the element name.
To define an element label, do the following:
1. Open the process diagram with the element.
2. Select the element.
3. In the Properties view, go to the Appearance tab and define the label in the Label field.
62
Modeling
Figure 2.54 Identical labels on multiple process elements
2.3.3
Defining Process Parameters
If your process is not instantiated automatically by its model (it might be instantiated a function call or a reusable
sub-Process, you can instantiate your Process with parameters:
To define process parameters, do the following:
1. Make sure the process is open in the process editor.
2. In the Outline view, right-click the process and select New > Parameter. Make sure to select the parameter
as Required if it cannot be null: if not required and the process is instantiated without the parameter, the
parameter value is null.
Alternatively, you can open the process properties in the Properties view and click Add on the Parameters
3. In the Property view, define the parameter properties.
When the process is then called, the call can provide arguments that can be used inside the process.
1 applicationForm(user -> admin, requestedHardware -> Hardware.ssd)
In the case of reusable-Subprocesses, the parameter values are defined on the Parameters tab of its Properties
view.
2.3 Processes
2.3.4
63
Defining Process Local Variables
Process local variables are accessible from within the process context and are initialized when the process instance
is created.
To define local process variables do the following:
1. Make sure, you have the process resource opened in the Process editor.
2. In the Outline view, right-click the process and go to New > Variable.
3. In the displayed Properties view, define the variable properties.
2.3.5
Inserting Tasks
A Task in Processes represents a piece of work of a specific type: the type of work is determined by its type. Each
task type specifies its own logic and the parameters it requires. Therefore whenever you insert a Task into your
process, you must define its task type and successively its parameters.
For example, a Task of the SendEmail type will send an email to a recipient. Sending an Email is its logic and the
recipient is passed as a parameter along with other parameters: email subject, body, sender and recipient's email,
attachments, etc.
You can find many useful Task types ready for useful in the module of the Standard Library; however, if you want to
create your custom Task type, you are free to do so: the Task type is stored in Task type definitions and references
its implementing Java class. For details and instruction on how to create a custom task type, refer to Software
Development Kit Guide.
To insert a Task as part of your process, do the following:
1. Open the process definition. If using GO-BPMN processes, make sure to open the respective Plan.
2. In the palette, select the Task and click into the canvas where you want to place the Task.
3. Select the type of the Task in the dialog box.
4. Define the task parameters: you can do so either in the Parameters tab of its Properties view or in the built-in
task editor after double-clicking the Task element.
Figure 2.55 Defining task parameters
The syntax of the parameter expression is a comma-separated list of key-value pairs:
1 <parameter1_name> -> <parameter1_value>,
2 <parameter2_name> -> <parameter2_value>
User Task parameters
1 title -> "My Pending Item",
2 performers -> {anyPerformer()},
3 uiDefinition ->
myTodoForm()
64
Modeling
2.3.5.1
Changing Task Type
To change the task type of an existing Task, right-click the Task in the canvas and click Change Type. In the dialog
box with task types select the new Task Type.
Note that the expression with parameter values remains unchanged and you will need to adapt the expression to
the parameter required by the new Task Type. To remove invalid parameters and keep only the parameters that are
relevant for the Task Types, run the Task Parameter Clean-Up (go to Project -> Task Parameter Cleanup).
2.3.5.2
Cleaning up Task Parameters
Task type parameter cleanup automatically removes parameters according to modifications performed in the underlying Task Type and irrelevant parameter values. To run the clean-up, go to Project -> Task Parameter Cleanup.
2.3.6
Extracting Process Elements into a Reusable Sub-Process
To nest one or multiple Process elements into a Sub-process, select the elements, right-click the selection, and in
the context menu, click Extract to Subprocess.
2.4
Global Variables
A Variable Definition file is a resource file with definitions of global variables, which are available throughout the
entire model. One module can contain multiple variable definition files. For information on global variables, refer to
the GO-BPMN Modeling Language Guide.
Note: Local variables on Process elements that represent a name spaces are defined outside of the
variable definition file as follows: ∗ on elements that represent a name space, that is Processes, Plans,
Sub-Processes, forms, and model update Processes, right-click the element in the Outline view, and
go to New -> Variable. In expressions, you can define local expression variables as def <TYPE>
<VARNAME>.
2.4.1
Defining Global Variables
To define a new global variable, do the following:
1. In the GO-BPMN Explorer, double-click the respective variable definition.
2. In the activated form-like Variable Editor, click Add.
Global variables are initialized in the same order they appear in the definition file: a variable defined lower,
can use a variable defined above.
3. In the Name text box, type the variable name.
4. In the Type text box, type the data type of the value that the variable is going to store.
5. Define the variable visibility:
• Select the Public checkbox to make the variable available to the world.
• Clear the Public checkbox to make the variable private (available only within the Module).
2.5 Organization Models
65
6. In the Initial Value text box specify the initial value of the variable: Type the initial value as an expression in
the Expression Language directly into the Initial Value field. If no initial value is specified, the value is set to
null.
7. Click Edit to open the Value Dialog dialog box and use the context menu of individual rows to specify the initial
value (refer to Writing Expressions).
8. To use the variable in an expression, simply enter the variable name, for example, to assign a value to a
variable: myGlobalVariable := "string variable value"
Note: Global variables are instantiated in the order they are defined in. Therefore, if you want a variable
to use another variable from the same namespace in its initial value, make sure the variable is defined
below the initialization variable.
Figure 2.56 Editing variable definitions
2.5
Organization Models
The organization model with its roles and units serves to group users, for example, with the aim to assign a piece
of work to such a user group. The group can be defined as an Organization Unit or role.
As part of user management, you can assign Roles and Units to users so as to defines their role in the business
process: When a user (person) has a particular Role or belongs to an Organization Unit, the system will include
them when resolving the group members for some action intended for persons with the role or unit.
To make the system return all persons with a particular role, you can use the <ROLE_OR_UNIT>(<PARA←METERS_MAP>). For example, to set the performers parameter of a User Task, you could use Software←Engineer(["foe" -> "PM1", "lang" -> "Java"]).
For further information on organization elements, their properties, and impact on work distribution, refer to GO-B←-
PMN Modeling Language Guide.
66
Modeling
2.5.1
Creating an Organization Model
To design an organization structure, do the following:
1. In the GO-BPMN Explorer, right-click the Module and go to New > Organization Definition or double-click
your organization definition or organization diagram.
The Organization Editor with a diagram of the definition appears in the editor area.
2. Design the organization: click an element in the palette and click on the canvas to place the element on
the diagram and create it in the definition file. Alternatively, you can then create further elements with the
quick-linker.
Figure 2.57 Editing the Main diagram of an organization definition file
3. Define additional properties for units and roles in their Properties view:
• On the Detail tab consider defining the label, a String that is used to represents the Unit or Role
Labels typically hold a human-readable name of a Unit or Role, for example, for a role QE, you could
define the label Quality Engineer. To display the name of the role in a form, you could use the
getLabel() function, for example, QE.getLabel().
• Define parameters of your units or roles if required in the Parameters tab.
2.6 Documents
67
4. When finished, click File -> Save to save the file or press Ctrl + s.
2.5.2
Assigning a Role or Organization Unit
You can add a person to a role or organization unit in the following ways:
• programatically from a Model instance with one of the addPersonToRole() function
• on runtime, from the management perspective or web management console.
2.6
Documents
Documents serve to presented the user with pages with business data that are not dependent on a process←: documents are available as long as their definition is on the server.
Documents are defined in the document definition: you can create one or multiple Documents in one document
definition. Typically, you want to create your documents in a dedicated Module to allow you to unload the Module
without side effects later if necessary. Once you have created a Module with document definitions, all you need to
do is upload the Module: The documents will be available in the Document tab of the process application as long
as the Module remains on the server.
The default application displays the list of Documents available on the server on the Documents tab:
68
Modeling
• When the user opens a document, the system creates a Model instance with all the context data and renders
and populates the document data.
• When the user submits the document, the document data is saved, typically in the underlying DB via shared
Records, and the model instance ceases to exist. Note that the document will remain available in the list
of documents since the list contains the types of documents, not their instances: Unlike To-Dos, documents
availability does not depend on a Process Task; they are available as long as the definition of the document
is on the server and their instances are created on request.
Figure 2.58 Form with a table in a document
2.6.1
Defining a Document
To define a new document, do the following:
1. Create a document definition file:
(a) Right-click your module.
(b) In the context menu, go to New > Document Definition
(c) In the New Document Definition dialog, define the definition file properties: check its location and modify
its name.
2. Open the document definition file.
3. In the Documents area of the Document Editor, click Add.
4. In the right part, define the properties of the document.
• Name: name of the document unique in the Module
• Title: document title displayed in the web application
The title is a String expression, which is re-evaluated on document refresh (for details on the refresh
mechanism refer to Process Application Forms User Guide).
• Parameters: list of input arguments of simple data types used by the document
Parameters are meant to pass data to the document. Note that documents with parameters are not
visible in the Documents list in the application.
• UI definition: expression that returns the UI definition, typically a form call
• Access rights: boolean expression that defines the condition that must be true to allow the front-end
user to access the document
2.6 Documents
69
• Navigation: a Navigation object that defines where to go when the document is submitted or cancelled
If you define the Navigation on your Document definition, the Navigation defined as part of the submit
is ignored (that is, if you define a button that submits the form, the form will navigate as defined in the
Navigation closure; not in the navigation of the submit component)
Note: The Navigation closure gets as its input parameter all To-Dos that were created when
the form called the createModelInstance() or a synchronous sendSignal() functions. For example, let's assume a document that references a form with a Button component.
The Button component defines an ActionListener with the handle expressions
createModelInstance(true, findModels("MyModel", 1.0, true)
[0], [->])
and
sendSignal(true, findModelInstances("MyModel", 1.0, true,
[->]), "Consider roll-back action.")
The To-dos created by the calls are returned as input for the Navigation closure so you can
define them or their modifications as the target Navigation object.
• Navigation Factory: function that will return the Navigation object to the Document and takes the same
parameters as the document
The Navigation Factory function can be then used in the Navigation expressions in forms so you do not
have to explicitly instantiate the Navigation object with parameters.
Example Navigation
1 getDateFormNavigation(1)
2 //instead of
3 //new DocumentNavigation(documentType -> dateForm(), parameters -> ["id" -> 1])
5. If applicable, upload your Module and check the Document on the Documents tab of the Process Application.
2.6.2
Navigate Away from Document
To define where to navigate when the user submits a document, define the Navigation property. Note that this
navigation overrides the navigation on submit defined on form listeners.
You can navigate, for example, to the following:
• to-do
1 {todos:Set<Todo> -> new TodoNavigation(todo -> getTodosFor(getPerson("admin"))[0], openAsReadOnly ->
false)}
To navigate to a to-dos create from the document, use the input parameter of the navigation closure that
holds to-dos created by a createModelInstance() or a synchronous sendSignal() functions: to
navigate to the first to-do created by the document form, define Navigation as
1 {todos:Set<Todo> -> new TodoNavigation(todo -> todos[0], openAsReadOnly -> false)}
• application page:
1 //navigating to the Documents page:
2 { s:Set<Todo> -> new AppNavigation(code -> "documents")}
• document:
1 //navigating to a document (creates a new document instance):
2 { s:Set<Todo> -> new DocumentNavigation(documentType -> myDoc())}
• saved document:
1 //navigating to a saved document; getMySavedDoc() is a query that returns a SavedDocument):
2 { s:Set<Todo> -> new SavedDocumentNavigation(savedDocument -> getMySavedDoc())}
• url:
1 //navigating to documents:
2 { s:Set<Todo> -> new UrlNavigation(url->"www.whitestein.com")}
70
Modeling
2.6.2.1
Creating a Model Instance and Navigating to its To-Do on Document Submit
To create a model instance from a document and then navigate to one of its To-dos, do the following:
1. Define a listener that will create the model instance:
(a) Attach a listener of the required type to a component.
(b) Create the model instance in its persist action, for example, createModelInstance(true,
getModel("myModelName"), null)
2. Define a listener with the Submit action (it represents the moment when you want to submit the data and
navigate away from the document).
3. In the document definition, define the Navigate property so it returns TodoNavigation to the required To-do.
1 \\navigates to the first to-do generated by the document:
2 {todos:Set<Todo> -> new TodoNavigation(todo -> todos[0], openAsReadOnly -> false)}
2.7
Forms
Important: UI forms do not support the Change Proxy mechanisms.
A form is a tree of form components that defines the content displayed in the front-end application. The form can
be displayed either by a document or by a to-do:
• When displayed by a document, the form is used as content of a page that is permanently available to the
user.
2.7 Forms
71
Figure 2.59 Form with a table in a document
• When displayed by a to-do, the form is used as a content of a to-do which is part of a process and disappears
once the user submits it.
Figure 2.60 Rendered to-do with the form
When the user opens a to-do or document that references the form, the following happens:
1. The system creates a execution level, called screen level with the form context.
2. The system initializes form variables and builds the form.
3. The form tree is rendered as web content and populated with the data from the context in the screen level.
A form is called as a function, and so it can take input parameters and define its local variables.
The behavior of form components is defined by event listeners: On runtime, when the form a listener catches its
event, the event is queued and processed in a event-processing cycle when it is triggered. The way the event is
processed is defined by the listener.
For example, if the user clicks a button, the button fires an event, called ActionEvent. The event is caught by the
ActionListener attached to the button component. It is the listener that defines what the event causes: The actions
taken might include refreshing of form component, persisting the data, submitting the to-do or document, etc.
72
Modeling
Important: The form implementation makes use of the Vaadin and Vaadin Charts frameworks. Make
sure to buy the relevant Vaadin Charts licences.
Every form component defines the following properties:
• ID: ID of the component on design time Note that the ID can be used by other form components and listeners
in the form to reference the form component. Only capital letters, digits, underscores and dollar signs are
allowed.
• Modeling ID: ID of the component used on runtime Modeling IDs are populated with a random unique value.
You can change the value manually if required. If an error occurs in a form on the server, the server returns
an error with modeling IDs of the involved components. The feature is disabled by default. You can enable it
with a parameter for your server.
• Visible: visibility of the component and its child components If the property expression is true or null, the
component is visible. If false, the component is not visible. The default value is true. Note that invisible
components and their child components are not recalculated on refresh.
Important: The Visible property substitutes the Show property, which was deprecated and removed. If you are using still using the Show property in your forms, it will be handled as expected.
If both the properties are defined, the Visible property takes precedence.
• context menu: menu displayed when the user right-clicks the component
• component-specific properties that define the behavior of the component (refer to sections on individual
components)
Apart from these generic properties, every component can define:
• presentation hints that define the presentation style of the component, that is, how the component is rendered
• listeners to react to events that occur on the component
You can create a custom form component that will be available in the form-editor palette just like standard components.
2.7 Forms
73
Figure 2.61 Form Editor with a Custom Submit Button
Related topics:
• Creating Forms
• Component Reference
• Patterns
• Enabling Error Reporting on Components
2.7.1
Form Execution Levels
A model instance state is defined by its properties and data of its context. When the model instance creates a
form, the context hierarchy is created on another execution level to isolate the form data. As a result, the changes
of such form data are applied only on the "real" data only when explicitly required: to-dos or documents with a ui
form are created on their own level that overlays the model instance level.
So while model instance contexts exist on the base level, when a model instance hits a user task or when a
document of model instance is created, the system creates a new level for the form of the document or task. This
context level is a copy of the base context level and is referred to as the screen context level: When the user
changes the data in the form, the changes are performed on the context of the screen level.
74
Modeling
Figure 2.62 Schema with execution levels of a model instance, and a to-do and form
Note that sublevels always hold only the differences to the context hierarchy in the superlevel.
To apply the changes, the user must merge the screen level into the base level: this happens when the form is
persisted. Persisting is performed as part of event processing: hence, to merge the screen level into the base level,
you need to create a listener that will perform the persist or submit action.
2.7.1.1
Evaluation Execution Levels
If you need to create another execution level over the screen level to isolate data within your form, you can do so
with a View Model component: the component creates another execution level referred to as an evaluation level.
The evaluation level overlays either the screen context levels or another evaluation level. When merging context
of an evaluation level, the context difference are applied on the data in the evaluation or screen superlevel.
Contexts on evaluation levels hold the differences to their contexts on the underlying level. When merging a
context of an evaluation level, the difference are applied on the contexts in the underlying evaluation or screen level.
Figure 2.63 Execution levels and contexts in Model instances as used for forms
2.7 Forms
2.7.2
75
Event-Processing Cycle
When the user or the system performs an action on a form component, the form component produces an event of
a particular type. If the form component has a listener for the type of the event, the event is usually immediately
processed in the event-processing cycle (The exception are non-immediate ValueChangeEvents).
The event-processing cycle, or request-response cycle, processes the event in a set of steps that gradually perform
actions defined on the listeners of the events. Note that multiple listeners might exist for one event: the event is
broadcast to all the listeners on the component.
You can find a detailed schema of the event handling.
Figure 2.64 Form event firing
Note: If a component has the immediate property set to false, its ValueChangeEvents are not processed immediately: Instead the ValueChangeEvents are kept in an event queue. When an event that
requires immediate processing occurs, all queued ValueChangeEvents and the immediate event are
processed in one event-processing cycle run.
The event-processing cycle performs the following:
• Updating of internal values (References to internal values are defined as bindings on form component.)
• Validating of values
• Executing of listener logic as defined by their handle expression
• Firing of any application events
• Merging or clearing of any View Models data
• Navigation expression is evaluated. However, the system does not navigate to the navigation target yet.
If a listener requests submit, the form is submitted and the event processing cycle finishes. If submit was not
requested and a processed listener fired an application event, the event-processing cycle is repeated and the newly
fired application events are processed. Otherwise, the components are refreshed and any produced Application←Events are processed. If no such events exist, the event processing cycle finishes.
76
Modeling
Figure 2.65 Event processing cycle
When the event processing finishes, the cycle executes the listener actions if requested, that is, the save, submit,
and navigate actions:
• Submit: defines if the document or to-do is submitted as part of the event handling;
• Persist: if enabled, the relevant data in the processed components is persisted as part of the event handling;
unlike on submit action, if the form is used by a to-do, the to-do does not become finished; if part of a
document, the document remains open; persist is performed after the merge to the screen level before the
transaction is committed.
• Save action: defines if the to-do or document is saved;
• Navigation: defines the location where to navigate after the event is processed; you can navigate to a to-do
or document, URL, custom application page (refer to the descriptions of data types defined in the human.←navigation.datatypes resource in the Standard Library)
Note that the event processing and the listener actions are executed within a single database transaction so that
if the processing fails at any stage, the database is rolled back to a consistent state. If events are processed and
listener actions are performed successfully, the transaction is committed and the request-response cycle finishes.
2.7 Forms
77
Figure 2.66 Database transaction on event processing and listener actions
Events Listeners
2.7.2.1
Events
When the user performs an action on a form component, such as, changing a value, clicking a button, moving a
widget, etc. the component produces an event of a type: the type depends on the action. The produced event holds
data about the actions. If the component had a listener that is listening for an event of the given type, it catches the
event.
Note: The underlying event type are available in ui.event.datatypes in the Standard Library.
These caught events are queued to be processed in the request-response cycle and either wait or trigger the
request-response cycle: if the event is immediate, it triggers the request-response cycle; if it is not immediate, it
waits in the queue until an intermediate event enters the queue and trigger the request-response cycle.
Some event types are immediate by default; other event types are non-immediate and can be set as immediate
explicitly if required.
All queued events are processed simultaneously: the way the events are handled and the actions they cause are
defined by the listeners that caught them; for example, a listener can request refreshing of form components, data
validation, etc.
Event Fields Usage:
Fields of event objects can be used to acquire further data about the particular event, for example,
the ChartClickEvent contains fields with details on where exactly on the chart the click occurred so the
listener can define different actions depending on the location where the user clicked.
Another feature the event fields enable is granulation of ApplicationEvents. Assume an application
form with personal details, application details, Reject and Accept buttons, and a Reusable form with
additional data on reject. If the user rejects the application, the provided data must be validated and the
reject form must appear and they must provide the relevant rejection data. If they accept the application,
no comment is required. However, all other components must be still validated.
The underlying form will define the two buttons with listeners that throw the OnSubmit Application←Event. However, the Reject button will throw an ApplicationEvent with the REJECT value as its payload
field, while the Accept button throws an ApplicationEvent with the ACCEPT value as its payload field.
The input component for the comment must therefore define an ApplicationListener that will check that
the ApplicationEvent payload is ACCEPT or if the payload is REJECT, it will check that the comment
component is not empty.
Form components produce events of different types depending on the action that created the event. Here is a brief
summary
78
Modeling
• All form components
– InitEvent produced when a component is initialized (a form or a previously hidden component is shown)
– ApplicationEvent produced when by any listener as part of their handling
Application events can be fired by any listener and are broadcast to all form components.
• All input components
– ValueChangeEvent produced when the user changes a value in an input component
The time when the change-value event is processed depends on the setting of immediate mode.
• Button and Action Links
– ActionEvent produced when the user clicks an Action Component
• File Download
– FileDownloadEvent produced when the user clicks a file-download button of a file-download component
• File Upload
– FileUploadEvent produced on file-upload completion
• Text Box and Text Area
– AsynchronousValueChangeEvent produced on every key stroke
• All Chart components
– ChartClickEvent produced when the user clicks a chart
• Widget
– WidgetChangeEvent produced when the user adds a widget to the dashboard, resizes, moves, or
hides a widget
• Calendar
– CalendarCreate event produced when the user selects a time period by clicking and dragging
– CalendarEdit event produced when the user clicks a calendar entry
– CalendarReschedule event produced when the user drags a calendar entry
• Geolocator
– Geolocation event produced when the Geolocator component acquires user's location
• Map Display
– MapClickedEvent produced when the user clicks on the map
– MarkerClickEvent produced when the user clicks on a map marker
– MarkerDraggedEvent produced when the user drags a map marker
• Table of the Paged Type
– TablePageSizeChangeEvent produced when the user changes the size of the table page
• Tree
– TreeEvent produced when the user expands or collapses a tree item, be it in a tree or a tree table
component
• Popup
– ∗∗PopupCloseRequestEvent∗ produced when the user click the close button in a popup
2.7 Forms
79
• Context menu
– MenuEvent produced when the user clicks an item in the context menu
Listeners for these events must be defined on the component that produces the event. To listen for an event on
another component, you can do one of the following:
• To listen for events from child reusable forms or to listen on events from parent forms, use Container interface
with public listeners and registration points.
• Produce an application event.
2.7.2.1.1
InitEvent
The InitEvent is fired when a component is shown, be it for the first time or after it was saved or when a component
becomes visible.
Property
Data Type
Description
source
UIComponent
Component that produced the event
isFirstLoad
Boolean
true for a component displayed for the first time (the property is true
also when a hidden component is displayed for the first time)
isFirstLoadAfterSave
Boolean
true for a component displayed for the first time or for the first time after
save
2.7.2.1.2
ValueChangeEvent
The ValueChangeEvent is fired by input components and that when the user changes a value in an input component
and changes the focus or on when they select an option.
Note: When ValueChangeEvents take effect depends on whether its input component is immediate
(defined as the Immediate property of the component).
If the component has the Immediate property set to true, the event is processed as follows:
• If on a Text Box or Text Area, the event is produced and handled when the component loses focus,
that is, after you edit the value and click another component or press Enter.
• If on Lists, Check and Combo Boxes, the event is produced and handled when an item is selected.
If the property is set to false, then the event is produced at the same time but remains unhandled,
that is, the request-response cycle is not triggered: Instead it is added to an event queue. The queued
events are processed on the next run of the request-response cycle, that is, when a ValueChangeEvent
with activate immediate mode or an event of another type is handled. This typically happens when the
user confirms the value changes by clicking a button (a listener for the ActionEvent must exist).
When a ValueChangeEvent occurs, the new value undergoes conversion validation before the events are actually
processed. On conversion validation, the server checks, if the new value has the correct form. If this validation fails,
the component is marked as invalid and the ValueChangeEvent, any ApplicationEvents and ActionEvents are not
processed any further.
Note that when you change a value in an input component, the value change is applied on the bound entity, such
as, a variable, even if no listener for the value change event exists. To prevent this behavior, use nested contexts.
80
2.7.2.1.3
Modeling
Property
Data Type
Description
source
UIComponent
Component that produced the event
oldValue
Object
Object with the value before changed
newValue
Object
Object with the value after changed
AsynchronousValueChangeEvent
The AsynchronousValueChangeEvent is fired and processed immediately when the user changes a value in a Text
Box or Text Area component.
The event is fired asynchronously: a new one can be fired even if the old one is still being processed.
2.7.2.1.4
Property
Data Type
Description
source
UIComponent
Component that produced the event
text
String
String with the input
ActionEvent
The ActionEvent is fired when an action or image component is clicked, when a file upload is started, and when
ENTER is pressed on the TextBox component.
2.7.2.1.5
Property
Data Type
Description
source
UIComponent
Component that produced the event
FileDownloadEvent
The FileDownloadEvent is fired when the File Download component is clicked.
2.7.2.1.6
Property
Data Type
Description
source
UIComponent
Component that produced the event
FileUploadEvent
The FileUploadEvent is fired when file uploading finishes. Note that on upload start, an ActionEvent is fired.
2.7.2.1.7
Property
Data Type
Description
source
UIComponent
Component that produced the event
uploadedFiles
Set<Files>
Set of uploaded files
errorMessage
String
Error message returned if the upload fails
ChartClickEvent
The ChartClickEvent is fired when a data point of a chart element is clicked.
The event contains the data series, key, and values of the clicked chart location. This allows you to implement, for
example, data drill-down.
2.7 Forms
2.7.2.1.8
81
Property
Data Type
Description
source
UIComponent
Component that produced the event
series
String
Label of data series that was clicked
key
Object
Key value for the data point
value
Decimal
First value defining the data point
value2
Decimal
Second value defining the data point
payload
Object
Payload of the data point
WidgetChangeEvent
The WidgetChangeEvent is fired when a widget is added, removed, resized, moved, or hidden.
Property
Data Type
Description
source
UIComponent
widget component that produced the event
widgetId
String
ID of the widget that produced the event set in the Widget ID parameter
configuration
WidgetConfiguration
Widget configuration with details about the widget visualization properties
2.7.2.1.9
CalendarCreateEvent
The CalendarCreateEvent is fired by a calendar component when the user clicks and drags over a period in a
calendar. The event hold the selection data as its payload and the data can be used to create a new calendar entry.
Property
Data Type
Description
source
Calendar
Calendar component that produced the event
from
Date
Start date of the selected period
to
Date
End date of the selected period
allDay
Boolean
If the entry is a whole-day event (if selected across days, the entry is an allDay entry;
if the selected area is across hours, the allDay property is false and the exact hours
are included)
2.7.2.1.10
CalendarEditEvent
The CalendarEditEvent is fired by a calendar component when a calendar entry is clicked. Note that the event has
as its payload the business object of the calendar entry that was clicked.
2.7.2.1.11
Property
Data Type
Description
source
Calendar
Calendar component that produced the event
data
Object
Business object of the calendar entry that was clicked
CalendarRescheduleEvent
The CalendarRescheduleEvent is fired by the calendar component when a calendar entry is dragged-and-dropped
to a different date. Note that the event has as its payload the business object of the rescheduled calendar entry.
Property
Data Type
Description
source
Calendar
Calendar component that produced the event
from
Date
Start date of the new period
to
Date
End date of the new period
data
Object
Business object of the calendar entry that was rescheduled
82
Modeling
2.7.2.1.12
GeolocationEvent
The GeolocationEvent is fired by the Geolocator component after the component has acquired the geographical
position of the user or when the request for location times out.
Property
Data Type
Description
source
Geolocator
Geolocator component that produced the event
position
Geoposition
Data on position including latitude and longitude, speed, altitude, etc.
failure
GeolocatorError
Type of error if locating failed
2.7.2.1.13
MapClickedEvent
The MapClickedEvent is fired by the Map Display component when the user clicks into the map.
2.7.2.1.14
Property
Data Type
Description
source
MapDisplay
Map Display component that produced the event
point
GeographicCoordinate
point that was clicked
MarkerClickedEvent
The MarkerClickedEvent is fired by the Map Display component when the user clicks a marker.
Property
Data Type
Description
source
MapDisplay
Map Display component that produced the event
makerData
Object
underlying marker business object (the respective object of the set defined in the
Markers property of the Map Display component)
2.7.2.1.15
MarkerDraggedEvent
The MarkerDraggedEvent is fired by the Map Display component when the user drag-and-drops a marker.
Property
Data Type
Description
source
MapDisplay
Map Display component that produced the event
makerData
Object
underlying marker business object (the respective object of the set
defined in the Markers property of the Map Display component)
newLocation
GeographicCoordinate
new marker position after dropped
2.7.2.1.16
MenuEvent
The MenuEvent is fired when the user clicks an item in the context menu.
2.7.2.1.17
Property
Data Type
Description
source
UIComponent
Component with the context menu
id
Object
id of the clicked MenuItem object
TreeEvent
The TreeEvent is fired when the user expands or collapses a tree item, be it in a tree or a tree table component.
2.7 Forms
2.7.2.1.18
83
Property
Data Type
Description
source
UIComponent
Parent Tree or TreeTable of the treeItem
treeItem
TreeItem
TreeItem object that produced the event
TablePageSizeChangeEvent
The TablePageSizeChangeEvent is fired when the user changes the size of a paged table.
2.7.2.1.19
Property
Data Type
Description
source
pageSize
Table
Integer
Parent Table
page size after the change
PopupCloseRequestEvent
The PopupCloseRequestEvent is fired when the user clicks the close button in the caption of a popup component.
2.7.2.1.20
Property
Data Type
Description
source
Popup
Popup that requested close
ApplicationEvent
The ApplicationEvent can be produced by any listener: it is the only event, the user can define: When a listener
catches its event, it can fire an ApplicationEvent as part of its logic. The event can be caught by any ApplicationEvent
listener in the form, and that including listeners on any hidden components and reused forms.
Property
Data Type
Description
eventName
String
Custom name of the ApplicationEvent
payload
Object
Custom event data
For example, let's assume a form for placing orders. It contains multiple nested reusable forms: one contains
customer details, another ordered items, and the last one invoicing details. All three reusable forms need to be
validated before the order can be placed. The Place Order button located in the parent form, will fire an Application←Event that will be handled by ApplicationEventListeners on the reusable forms. The listeners will trigger validation
and any other actions needed as part of the event handling.
2.7.2.2
Listeners
Listeners are defined on form components and listen for events that occur on those components.
There a various types of listeners and each type listens for a particular event type: When the component produces an event of the expected type, the listener catches the event and sends it to the request-response cycle for
processing. The event is processed as defined by the properties of its listener:
• Basic properties determine what events are handled and how their are handled:
– Listener type: the type of event the listener handles
A listener catches only events with the same type as the listener type. You can use the Generic Listener
if you want to handle any events on a component.
84
Modeling
– Refresh components: comma-separated list of component IDs that are refreshed when the event is
processed
When components are refreshed their content is recounted and the component is re-rendered.
– Validators: validation expression
Event is handled only if the validation expressions are true.
– Data validation: validation expressions that validates against Constraints
When using data constraints, the expression should include a validate() call that will trigger the
constraint validation.
– Execute if other validations failed: setting to ignore failed validation on other than ValueChange←Events (refer to chapter on the setting)
– Execute even if invalid components: enforces execution of the listener logic even if the form contains
incorrect data, such as, "aaa" instead of an integer to allow operations as refresh or reset on click.
– Handle expression: expression that is executed
The expression represent the action the listener performs to handle the event.
– Event identifier: identifier of the received event
You can use the identifier in the Handle expression to acquire the event details, such as the component
that produced the event, uploaded files, etc.; refer to Filtering Events on Listeners.
• Advanced properties defines the context of the listener execution and actions on any overlay contexts as well
as handling pre-condition:
– Process components: comma-separated list of component IDs; only events produced by the components are included it the event processing cycle
The property allows you to ignore some components of the form, typically, if you have a form with
multiple tabs and you want to ignore events with their validation on anther tab, or to prevent validation
on all components when resetting the content of one component.
This property is applicable only on listeners defined on components with the Immediate mode deactivated (the Immediate property set to false). For such components, the fired ValueChangeEvents are
not processed immediately but wait either or an event of another type or a ValueChangeEvent that was
fired by a component with the immediate mode activated. Then all queued events are processed if the
Process components property is null. However, if the property is not null, only the ValueChangeEvents
fired by the components defined in Process components are processed.
– Execution context: execution context of the listener
All expressions defined in the listener properties, such as, its precondition, validation, etc. are evaluated
in this context.
* default: the context level of the component on which the listener is defined
* top level: the screen context of the form
* component: ID of the component which represents the target execution context
Important: The execution context setting does not influence how View Models are
merged: this is set by the merge type property on the View Model.
– Execution only if visible components: comma-separated list of component IDs; the event handling
takes place only if all specified components are displayed in the form.
– Clear/merge view model components: IDs of view models (their contexts are cleared or merged to
the target execution level).
– View model init: expression executed right after the merge or clear of view model components
The expression serves as a hook after the merge-clear phase.
– Precondition: pre-condition for event handling
If the pre-condition evaluates to false the event is not handled.
• Actions properties define what actions are performed on the to-do or document after the event is processed:
– Submit: defines if the document or to-do is submitted as part of the event handling;
If enabled, the relevant data in the components is persisted and the to-do becomes finished or the
document closes.
2.7 Forms
85
– Persist: if enabled, the relevant data in the processed components is persisted as part of the event
handling; unlike on submit action, if the form is used by a to-do, the to-do does not become finished;
if part of a document, the document remains open; persist is performed after the merge to the screen
level before the transaction is committed.
You can define a persist action, which is performed immediately after the persist.
– Save action: defines if the to-do or document is saved;
The save action saves the current state of the to-do or document for later editing, which includes saving
the provided data; it is identical to clicking the Save button on a to-do or document in the LSPS Process
Application) the save action does not persist the data; therefore make sure to define the Persist property
if required. If a newer version of the saved to-do or document is available, the application displays a
notification.
Note: A saved document is persisted in the system database as the SavedDocument record. If
saved repeatedly, the same record is overwritten; hence only the last saved document version
is available. On submit, the persisted document is removed. For more information on the
record type and related functions, refer to the Standard Library documentation.
– Navigation: defines the location where to navigate after the event is processed; you can navigate to a
to-do or document, URL, custom application page (refer to the descriptions of data types defined in the
human.navigation.datatypes resource in the Standard Library)
Note: Navigation takes place after persisting, which allows you to use the persisted data in
the navigation expression.
– Fire application event: ApplicationEvent the listener produces
2.7.3
Creating Forms
When creating forms, you will typically do the following:
• Create a form definition.
• Create form parameters and variables.
• Design the form-component tree and its behavior.
2.7.3.1
Defining Process Parameters
To define form parameters, do the following:
1. Make sure the form is open in the form editor.
2. In the GO-BPMN Explorer, right-click the form and select New Parameter.
Alternatively, you can open the form properties in the Properties view and click Add on the Parameters tab.
3. In the Property view, define the parameter properties.
When the form is then called, the call can provide arguments that can be used inside the form.
1 applicationForm(user -> admin, requestedHardware -> Hardware.ssd)
86
Modeling
2.7.3.2
Defining Local Form Variables
Form variables are initialized when the form is displayed, that is, when an InitEvent is fired. In your forms you should
prefer local variables over global variables so as to keep your presentation data separated from the business data.
Note: If you need business data in your form that is not yet available when the form is displayed,
process the InitEvent with an InitListener. The event is fired and processed when the component is
displayed. However, note that it is not possible to fire an InitEvent so the init of your data can
occur only once.
To define local form variables do the following:
1. Make sure you have the form resource opened in the Form editor.
2. In the Outline view, right-click the form and go to New > Variable.
3. In the displayed Properties view, define the variable properties.
2.7.3.3
Designing Form Tree
To create the content of your form, open the form definition file (double-click it in the GO-BPMN Explorer). Then
either click the required component in the palette and then click into the canvas to insert it, or right-click the canvas,
go to Insert Component and select the component from the context menu.
If your form requires CRUD components, consider using the Scaffolding library.
Figure 2.67 Inserting a component into the form from the context menu
Note: Alternatively, you can create forms with dynamic-gui functions, such as createAndAdd().
However, these functions are not supported.
Once you have created your form or while doing so, you can do the following:
• define basic behavior of the form and its components
• define validation
• reuse form components
• modify presentation properties of components
• define mobile forms
2.7 Forms
2.7.3.3.1
87
Inserting a Parent Component
You can select one or multiple form Components and wrap them with another components in the Form graphical
editor.
To insert such a parent form component over another component, do the following:
1. In the Form editor, right-click the component.
2. In the context menu, go to Insert Parent and select the component to use as the wrapper component.
Figure 2.68 Wrapping component in a layout component
2.7.3.3.2
Deleting a Parent Component
To delete a only a parent component and preserve its child components, right-click the parent component and click
Shift Children Up.
Note that the option is only available if the children can be accommodated in the form after the deletion; for example,
it is not possible to delete a Vertical Layout with multiple child components if it has a Panel component as its parent.
2.7.3.3.3
Previewing Forms
While creating a form, you can display its preview in the browser.
Make sure a local LSPS Server is running.
When displaying a form preview, the server runs a persisted instance of the model that contains the form definition
(global variables are initialized, the Form parameters are initialized, the form screen context is created). The model
instance is persisted.
To display preview of your form in your web browser, do the following:
1. In the GO-BPMN Explorer, right-click the form.
2. Select Run As -> Form Preview and on the displayed application page in your browser, log in to the application.
In the Management perspective, you can delete any model instances that you triggered as form previews in the
Model Instances view: right-click anywhere into the view and click Remove All Form Preview Model Instances.
88
Modeling
2.7.3.3.4
Displaying Form Source
Since forms are defined as functions and their components as local variables of the respective record type on the
level of the Expression Language, you can display their source in the Expression editor:
1. In the Form editor, right-click any form component.
2. On the context menu, select Display Form Expression.
2.7.3.3.5
Searching for Form Components
If an error on a form component occurs during runtime, the server returns an error message with the modeling ID
of the form component. To search for the form component that caused the error in the current workspace, do the
following:
1. Go to Search Find Form Component.
2. In the displayed search dialog, enter the ID.
2.7.3.3.6
Defining a Context Menu
Every form component can define its context menu. The menu and its content is defined as a component property.
When the user right-clicks the component, the context menu with its items is displayed. The user can then click a
context menu item. On click, a MenuEvent is produced. The MenuEvent has the id of the clicked menu item as its
payload so the form can define the MenuListener that will trigger the respective actions.
The context menu can be defined as static or dynamic: A static context menu is calculated only once before the
form is rendered, while a dynamic context menu is recalculated on every right-click. This might cause performance
issues since it could require accesses to server on every right-click.
If you define both, a static and a dynamic context menu, on right-click, the displayed context menu will contain the
static menu items on top and the dynamic menu items below.
To define a context menu on a component, do the following:
1. Select the component in the form definition.
2. In the Properties view, open the Context Menu tab.
3. On the tab define either a static context menu or a dynamic context menu.
1 [new MenuItem(
2
caption -> "Open the Detail",
3
htmlClass -> "contextmenu",
4
id -> 0,
5
submenu -> [new MenuItem(
6
caption -> "Open in a New Tab",
7
htmlClass -> "contextmenu",
8
id -> 1),
9
new MenuItem(
10
caption -> "Open in This Tab",
11
htmlClass -> "contextmenu",
12
id -> 2)
13
]
14
)
15 ]
2.7 Forms
2.7.3.3.7
89
Defining Component Listeners
You can define listeners on any form component; however, every component type allows only listeners for events it
can actually produce; for example, a Button component can define only an Action listener, which is fired when the
user clicks a button. It cannot define a ValueChange listener, since the user cannot change any values on a Button.
To create a listener on a form component:
1. In the Form editor with your form definition, select the form component.
2. In the Properties view of the component, click the Event Handling tab.
3. In the Private Listeners section, click Add.
4. In the Add Listener view, define the Listener properties. Note, that if a tab contains a change of property
values, its tab label is bold.
Figure 2.69 Defining an ActionEvent listener on a submit Button component
2.7.3.3.7.1
Excluding Events
2.7.3.3.7.2
Filtering Events on Listeners
To filter out an event so the listener does not handle it, use one of the following listener properties:
90
Modeling
• Execute only if visible components: The event is processed by the listener only if the component that
produced the event is visible.
• Precondition: The event is only processed if the precondition evaluates to true.
1 if ((_event as ApplicationEvent).payload as Integer) == 1
2
then true
3
else false
4 end
• Event name (available only for ApplicationEventListeners): An application event is only handled by the listener, if the name of the event matches the defined event name.
The properties are defined as properties of the respective listener.
Note: An event might not be processed also if the validation process fails.
2.7.3.3.7.3
Filtering Queued ValueChangeEvents
If you want to ignore some queued ValueChangeEvents when a listener is triggered, define on the listener the Process component property: the property defines a list of form components whose ValueChangeEvents are included
in the event-processing cycle. Any other ValueChangeEvents remain in the queue.
For example, let's assume a table with column A and column B. Both columns contain input components that are
not-immediate and buttons used to submit the values from the given column. When the user changes values,
ValueChangeEvents from both columns are kept in the event queue. Then the user clicks the submit button in
column A. The value change listener must define as its Process component only column A. If it defines as its
Process component column B as well, all the ValueChangeEvents will be processed.
2.7.3.4
2.7.3.4.1
Generic Actions on Forms
Refreshing Form Components
To refresh the content of form components, do the following:
1. Define IDs on the component you want to refresh.
2. Create a private listener on the component that should cause the refresh.
(a) In the Properties view of the component, click the Event Handling tab.
(b) In the Private Listeners section, click Add.
(c) In the Add Listener view on the Basic tab, define the Listener properties:
• Listener type: the type defines the event type the listener handles.
• Refresh components: define IDs of the components that should be refreshed when the event is
handled.
2.7 Forms
91
Alternatively, you can call the refresh() function from the handle expression (for example, refresh([MYTABLE,
MYPOPUP])).
Figure 2.70 Listener that refreshes multiple components
2.7.3.4.2
Saving Documents and To-Dos
The Save action of a listener saves the current state of the to-do or document for later editing, which includes saving
the provided data; it is identical to clicking the Save button on a to-do or document in the LSPS Process Application)
the save action does not persist the data; therefore make sure to define the Persist property if required.
Note: A saved document is persisted in the system database as a SavedDocument record. If saved
repeatedly, the same record is overwritten; hence only the last saved document version is available.
On submit, the persisted document is removed.
The Save action expression is a closure that has the saved to-do or document as its input parameter. It serves to
further process the saved document or to-do; for example, store the to-do or document in your own data source.
Note that the returned Object is ignored: It is the closure that must perform the required steps.
To implement this feature, you will need to define the following:
• a shared Record that is in the 1:1 relationship to the human::SavedDocument record
• a document or a todo that will contain a form with a listener that will save the data as
your SavedDocument subrecord in its Saving Action expression
• implementation that will recover the saved documents, for example, another dedicated Document with a
navigation
• possibly the option for deletion of saved documents
Note that by default, the save action does not save Column states (width and collapse state). To save these, process
as described in Saving Column Width and Collapsed State.
92
Modeling
2.7.3.4.3
Persisting
To merge the form data into the base-level context as part of the event handling, enable the Persist action on the
Action tab of your listener properties.
Note that the scope of data that is persisted depends on the Process components setting: if the setting defines a
set of form components, only the data of these components are persisted.
Below the Persist checkbox, you can define a persist action, which is performed immediately after the persist, if
applicable.
Alternatively, you can call the persist() function from the handle expression.
2.7.3.4.4
Submitting
When the user submits the document, the document data is persisted, that is, the screen context is merged into
the base context, and the model instance ceases to exist. Note that the document will remain available in the list of
documents since the list contains the types of documents, not their instances: Unlike To-Dos, documents availability
does not depend on a Process Task;
To define, when the document is submitted, do one of the following:
• on the component that should submit the document, create a listener of the required type and on the Action
tab in the listener properties, select Submit.
Figure 2.71 Submit action on a click listener
• on the component that should submit the document, create a listener of the required type and call the
requestSubmit() or requestSubmitAndNavigate() from the Handle expression.
2.7 Forms
93
Figure 2.72 Submit call from a listener handle expression
2.7.3.4.5
Navigating Away
To navigate to a location when the form is submitted or saved, defined the Navigation on the Action tab of the
listener: you can navigate to a to-do or document, URL, custom application page (refer to the descriptions of data
types defined in the human.navigation.datatypes resource in the Standard Library).
Navigation expression
1 //redirect to the document Confirmation when the event is handled:
2 new DocumentNavigation(documentType -> confirmationDocument())
Note: Navigation expression is evaluated right after persisting, which allows you to use the persisted
data in the navigation expression. However, the action is taken only after the submit or save action is
performed.
2.7.3.5
Creating CRUD Components
You can create CRUD components for data of a particular type efficiently with the Scaffolding Library framework:
The framework serves for quick prototyping of forms that allow the user to create, read, update, and delete
objects of a particular data type so they do not have to create such components themselves.
The library provides a custom form component, GenericView, which allows you to create a form component over a
data type or data-type instances. By default the component renders as a CRUD table for the data type; however
you can change the component definition in the component properties to render as another component.
Important: The Scaffolding library resources are not optimized and hence not intended for production
environment.
94
Modeling
2.7.3.5.1
Generic View
The Generic View component is a custom form component that creates and renders a component, by default a
CRUD table, over instances of a particular data type or a data type.
In the default CRUD table, the columns represent the data type structure and the rows the data type instances: For
example, if you have a Record Book with the fields ISBN and title and you use it as the data type of the Generic
View component, the rendered table will have the columns ISBN and title. If you use a Record instance, the table
will in addition contain a row with the book's ISBN and title. From the table you will be able to create a new book
instance, and delete and modify the book instances.
The Generic View component has the following properties:
Object Object or a list of Objects that are populating the form component and defining its structure
If not overriden by the Record options property, the fields of the underlying data type are used as CRUD table
columns and every row represents one object.
Editable Whether the values are read-only or can be edited
If false, the table is read-only.
Data type If the component is editable and the Object expression returns an empty Collection, the system assumes
the Collection items are of the data type defined by this property.
It is recommended to define the Data type property since if the collection returned by the Object parameter is
empty, the front-end layer of the system considers the collection data type to be Null.
Recursion Depth The number of relationships of the displayed data type (Record) that is displayed directly in the
component of the top data type (Record)
If applied, the related data types are displayed as nested components which you can expand directly in the
parent component. Otherwise, the data is displayed on a new page and the depth is indicated only in the
breadcrumb.
Submit Button The component rendered instead of the default Submit button
Note that you can use a layout component to insert, for example, multiple buttons to where the Submit button
is located by default.
Record options Custom Record rendering
If defined, the system does not use the generic CRUD table but the form defined in this map to render the
Record whenever it appears in the Generic View.
1 [
2
Author -> new RecordOptions(
3
linkDisplayName -> {o:Object-> cast(o, Author).name},
4
recordCustomForm -> {o:Object -> new OutputText(content ->{->"anonymous"})}
5
),
6
Book -> new RecordOptions(
7
propertyVisibilityDefault -> false,
8
propertyOptions -> [
9
Book.name -> new PropertyOptions(
10
propertyVisibility -> true
11
),
12
Book.authors -> new PropertyOptions(
13
propertyVisibility -> true
14
)
15
]
16
)
17 ]
2.7 Forms
2.7.3.5.2
95
Recursion Depth
When using Records as data for a Generic View component and the Record type has a Relationship to another
Record, the Record instance is rendered in its own component (the CRUD table by default) which is displayed in a
popup window on request. To display such objects directly in the parent component, define the Recursive property
on your Generic View. If the Record instance is "within" the reach of the recursion, the component of the Record is
rendered as a nested component that can be expanded. If this is not the case, the Record instance is displayed in
a pop-up dialog box after clicking the view icon on the parent Record instance.
Figure 2.73 Document with Generic Views
The top Generic View has the Recursive depth property set to 0 while the bottom Generic View has the Recursive
depth set to 2.
Note: In the background the system always loads the data within the reach of one relationship, so that
when requested the data is already available.
2.7.3.5.3
Using Generic View
Before you can make use of the library, you need to import it into your Project and Module:
1. In the GO-BPMN Explorer, right-click your Project, click Add Library; in the popup select Select a built-in
library and select the Scaffolding Library in the Library drop-down box.
2. In the GO-BPMN Explorer, click the module. In the Imports tab of the Properties view, click Add. In the
pop-up, select the scaffolding module.
To create a form with the scaffolding component, do the following:
1. Create or open a form definition.
96
Modeling
2. Insert the Generic View custom component.
Figure 2.74 Generic view in palette
3. Define the required Generic View properties:
• object: expression that returns an object or a collection of objects that you want to work with in the
component
• editable: whether the objects are editable
• object type: data type applied if the object expression returns an empty collection as the data type of
the collection objects
4. Define the optional properties:
• recursion depth: the depth of the data types (Records) displayed directly in the component
• submit button: component rendered instead of the Submit button
Note that this expression has no impact on the OK & Persist button, which is displayed when creating
a new instance in a Collection of shared Records from the Generic View.
• record options: custom rendering of the Records
5. Run preview of the form on the Embedded Server if applicable: right-click the form definition and go to Run
As > Form Preview.
2.7.3.6
Validating Form Data
You can validate data in your form with using of the following:
• automatically triggered validation that is performed as part of the event processing directly on listeners as one
of the following:
– Validators: set of expressions that check if values in the form are valid and return a String with an error
message if they are not
The String is displayed as an error message on the defined form component: either the one defined in
the Error placement property.
– Data validation: expression that returns a set of constraint violations rendered automatically on the
components with the violations
2.7 Forms
97
• explicitly triggered validation that you can perform from the Handle expressions of your listeners
You will need to collect a set of constraint violations, typically, by calling the validate() function on the
respective Record, and then the showDataErrorMessages() function to display the violations in the
form.
Note: Constraints represent sets of rules that restrict the validity of a Record. Typically you will call
the validate() function on a Record to obtain the violations. For further information refer to the
documentation on Record validation.
2.7.3.6.1
Defining Validation in Listener Handle
When validating a Record in the Handle expression of a Listener, do the following:
1. Collect a list with constraint violations; typically you will use the validate() function on the record or
property.
2. Call showDataErrorMessage() function to display the error messages of the violation on the respective
form components.
Figure 2.75 A record validated as part of a listener's Handle
98
Modeling
2.7.3.6.2
Defining Automatic Form Validation
You can define both, validators and data validation, on listeners on their Basic tab:
• Validators with validator expressions that return a String when they fail, for example, if search←-
Var!=null and length(searchVar)>0 then null else “Provide search string!”
end.
The String is displayed as an error message on the defined form component: either the one defined in the
Error placement property
• Data Validation as an expression that returns a list of ConstraintViolations: to obtain such a list, use the
validate() function. in the case of Validators or the component bound to the validated Record or Record Field
in the case of Data Validation.
If you need to display a constraint violation on a particular component, create a constraint violation with record or property set to the same binding as your component; for example, [new
ConstraintViolation(payload -> null, record -> selectedRecord, property
-> LookupValue.displayName, guid -> null, id -> null, message -> "←Incorrect value.")]
The automatic validation passes only if:
• all validator expressions from the entire form return null and
• data validation expressions from the entire form does not return any validation constraints.
Figure 2.76 Listener with validators and data validation
2.7.3.6.3
Validation of non-ValueChangeEvents
Validation of ValueChangeEvents is governed by their own validation mechanism: they are executed always when
their validation passes regardless of other failed validations on other listeners. Also their Execute if other validations
failed setting is not taken into account.
In addition, validity of ValueChangeEvents has no impact on the general validity of non-ValueChangeEvents.
2.7 Forms
99
Consider the form below: the ISBN text box is in non-immediate mode and its ValueChangeListener defines a
validator for the entered text: it must be at least 18 characters long. The Submit button has an ActionListener with
the Execute if other validations failed property set to false and executes submit (the Submit property is selected).
Figure 2.77 Book Create Form
If the user enters less than 18 characters in the ISBN text box and hits Submit, the invalid value is persisted and the
form is submitted: the ActionListener on the Submit button ignores that the validation of the ChangeValueListener
failed.
Impact of Listener Validations on their Execution:
Listener
Listener Type
Execute if Other Validations Failed
false
Executed
Non-ValueChangeEvent
Listener Validation Outcome
fail
A
B
Non-ValueChangeEvent
fail
true
no
C
Non-ValueChangeEvent
pass
true
yes
D
Non-ValueChangeEvent
pass
false
no
E
ValueChangeEvent
fail
true
no
F
ValueChangeEvent
pass
false
yes
G
ValueChangeEvent
fail
false
no
no
We assume that the listeners in the table exist in one context:
Listener A and B Validation on Listeners A and B failed and hence they are not executed regardless of their
Execute if Other Validations Failed setting.
Listener C Validation on Listener C passed and its Execute if Other Validations Failed setting is true; hence it
ignores the failed validation on A and B and it is executed.
Listener D Validation on Listener D passed. However, since its its Execute if Other Validations Failed setting is set
to false and validation on other non-ValueChangeListeners (A, B) failed, it is not executed.
Listener E Listener E is a ValueChangeListener: its validation failed and hence it is not executed. The Execute if
Other Validations Failed setting is ignored.
100
Modeling
Listener F Listener F is a ValueChangeListener: its validation passed and hence it is executed. The Execute if
Other Validations Failed setting is irrelevant.
Listener G Listener G is a ValueChangeListener: its validation failed and hence it is not executed. The Execute if
Other Validations Failed setting is irrelevant.
2.7.3.6.4
Handling an Event When Validation Failed
If necessary, you can force the system to execute a particular listener even after the total validation had failed:
Ignoring failed validations on other listeners allows you to perform an action even if the form contains invalid values.
It is then enough that the validation on that particular listener passes for the event to be handled: failed validations
on other listeners are ignored.
This behavior is activated by the Execute if other validations failed property of the listener.
2.7.3.6.5
Filtering Validation Errors
When using validation of constraints on form components, by default, validation errors are displayed on the form
component that contains the value with the error. However, you can define explicitly additional validation errors
displayed on the component or hide such validation errors on the component:
• Excluding validation errors is intended for filtering of errors, so that only a subset of the errors is displayed on
the form component.
• Including validation errors defines additional validation errors displayed on the component.
These could be errors that would otherwise remain hidden. For example, when editing multiple record fields,
which would result in an overall record constraint violation, the error for the entire record would not be displayed since there is no form component that references the entire record.
You can define the excluded or included validation errors on the Validation Errors tab of the form component properties.
2.7 Forms
101
Figure 2.78 Including a Validation Error on a Form Component
If you want to ignore invalid data in a form and enforce processing of an event, select the Execute even if invalid
components setting for the given listener: the listener will be always executed as part of the next event processing.
2.7.3.7
Reusing Forms
If you want to reuse a form, insert it into your current form with the Reusable Form component. On runtime, the
component inserts the referenced form into your form tree and renders it as its part.
It is important to realize that events of the referenced forms are not visible to the parent form and vice versa. To
enable them to handle each others events, you will need to define public listeners or registration points:
• To catch an event produced by a parent form and handle it in the reused form:
1. Wrap the reused form component in a Container component.
2. Define a Public Listener that will listen for the event in the parent form.
3. Add the Public Listener to the parent form.
Detailed instruction are available in Sending Events to a Reused Form.
Note: If a public listener needs to listen on another higher parent context, you can register the listener
as a delegate listener on the mediating Container.
102
Modeling
• To catch an event produced by a reused form and handle it in the parent form:
1. Wrap the reused form in a Container component.
2. Define a Registration Point that will expose the respective component.
3. Define a Private Listener on the parent form that will be registered with the Registration point.
Detailed instruction are available in Receiving Events from a Reused Form.
Note: Registration points are implemented as a reference to the set of listeners defined on the Container component. If an event of the given type is fired within the form, it is handled as defined by the
registered listener of the parent form.
Figure 2.79 Schema of listener exposure in reusable forms with indications on how the events flow
Another way to handle events with listeners that are not defined on the component is to use Application Events:
Application Events can be created by a listener of any type and handled by one or multiple listeners of any form
component and that even if the component is hidden or located in a reusable form. Therefore it is not necessary
to define any interfaces to handle Application Events. Note that this mechanism can result in an involuted form
definitions which are difficult to debug; therefore it is recommended to use Application Events sparingly.
2.7.3.7.1
Receiving Events from a Reused Form
If a form needs to handle an event that occurs in the form of its Reusable Form component, you need to expose
the event using a registration point on the form referenced by the Reusable Form component and define a private
listener with the required Actions on the Reusable Form component.
2.7 Forms
103
Figure 2.80 Listening for events that occur in a Reusable Form component
Note that if you need to expose an event that occurs in a form that is included via multiple Reusable Form components, you need to mediate the registration points into upper forms.
To define such event handling, do the following:
1. Create or open the child form that will be referenced by the Reusable Form component of a parent form:
(a) Insert the Container component as the root component of the form.
(b) On the Container, define the registration point that will register the listener of the parent form:
i. Select the Container.
ii. Go to the Properties view.
iii. In the Interface properties, click the Listener Registration Points tab and click Add.
iv. In the Add Listener Registration Point dialog box, define the registration point properties:
• Name: name of the listener defined on the Reusable Form component
• Components: IDs of the components the listener listens on
104
Modeling
2. Create or open the form definition that will reuse the form you just created:
(a) Insert the Reusable Form component available under the Special Components and define its
properties:
(b) As its Form property, set the form from the previous step.
(c) On the Event Handling tab in the Private Listeners section, create a private listener with the following
properties:
• Listening on registration point: the registration point you defined on the Container of the reused
form (use autocompletion)
• Any other relevant listener properties.
2.7 Forms
105
Figure 2.81 Reusable form component with a private listener for a registration point
3. Test your form on the Embedded Server: right-click the form definition, go to Run As > Form Preview.
2.7.3.7.1.1
Receiving Events from a Reused Form across Multiple Reusable Forms
If a form needs to handle an event that occurs in a Reusable Form of another Reusable Form component, you will
need to delegate the Registration Point through the mediating Reusable Forms:
1. Create the child form that will be referenced by multiple Reusable Form components.
The form must have the Container component with the registration point as its root component.
2. Create or open the mediating form:
(a) Insert the Container component as the root component.
(b) Insert the Reusable Form component that references the reused form step 1. Make sure to define its
ID.
(c) On the Container component, create Registration Points that will mediate the Registration point from
the reused form:
i. Open the Properties view of the Container.
ii. On the Interface tab, click the Listener Registration Points tab and click Add.
iii. In the dialog box, define the registration point properties:
• Name: name of the registration point
• Components: ID of the Reusable Form component
106
Modeling
• Target registration point name: registration point of a child Reusable Forms (use autocompletion)
It is this property that connects the form to the Registration Point in the child Reusable Form.
3. Create the form that will handle the mediated event: insert the Reusable Form component that references the
respective mediating form and create a private listener on the component.
2.7.3.7.2
Sending Events to a Reused Form
If a Reused Form needs to handle an event from other form components, you need to insert a public listener into
the Reusable Form component that will listen for the event.
Figure 2.82 Public listener and its counterpart: added public listener on the parent
Note that if you need to send an event via multiple Reusable Form components, you need to expose the public
listeners using delegated listeners
2.7 Forms
107
To define such event handling, do the following:
1. Create the form you want to use as the Reusable Form (this form will listen to an event on its parent form):
(a) Create the form.
(b) Insert the Container component as the root component of the form.
(c) Define a public listener on the Container component:
i. On the Interface tab of the Container properties, select the Public Listeners tab.
ii. Click Add next to the New Listeners section.
iii. Define its properties: make sure to select the correct listener type.
Figure 2.83 Container with the public listener navigationLinkClick
2. Open or create the form that will use the created form in the Reusable Form component:
(a) Insert the Reusable Form component available under the Special Components and define its
properties: Make sure to define its ID and the referenced form.
(b) Create the component that will throw the event you will process in the reused form.
(c) Register the listener on the component:
i. Display its Event Handling tab in the Properties view.
ii. Click Add in the Public Listeners section and define the properties of the public listener:
• Component: the Reusable Form component that should process the event
• Listener name: name of the listener you defined on the form in the previous step (use autocompletion)
108
Modeling
If applicable, consider setting the Immediate property on the input component to true.
2.7.3.7.2.1
Sending Events to a Reused Form across Multiple Nested Forms
To expose a listener of a reused form across multiple parent forms, define a delegated listener in the mediating
forms: This will allow the child reusable form to listen for events that occur in other than the immediate form.
1. Create the form you want to use as the Reusable Form with the Container component with a public listener.
2. Delegate the public listener through the Container interface of other forms with Reusable Forms
components:
(a) Create or open the mediating form with the Container component.
(b) Insert the Reusable Form into the Container. Make sure to define its properties including its ID and the
referenced form.
(c) Delegate the public listener of the Reusable Form:
i. Select the Container component, and click the Interface tab in its Properties view.
ii. Select the Public Listeners tab and click the Add button in the Delegated Listeners section.
iii. Specify the delegated listener parameters:
• Name: name of the delegated listener
• Component: the Reusable Form ID
• Listener name: name of the listener of the reusable form (the one you are mediating; use
autocompletion)
2.7 Forms
109
Figure 2.84 Defining properties of a delegated listener
3. To delegate across further Reusable Form components, repeat the previous step.
4. Open or create the form that will use the created form in the Reusable Form component and create a public
listener on the Reused Form.
2.7.3.7.3
Broadcasting an Event
To broadcast an event across the entire form, throw an ApplicationEvent: an ApplicationEventListeners is thrown if
defined on a listener as part of the event-processing lifecycle. You can then define ApplicationEventListeners on the
form to catch and process the event as applicable.
To define an application event that will be thrown by the event-processing cycle, do the following:
1. Create a listener on the component that should give rise to the event.
2. Open the properties of the listener (on the Event Handling tab of the Properties view, double-click the listener).
3. In the Edit Listener window, go to the Actions tab.
4. In the lower part of the tab, check the Fire application event checkbox.
5. In the area below, enter the expression that creates the application event.
1 new ApplicationEvent(eventName -> "idCreateRequest", payload -> idInfo)
You can now define the ApplicationEventListeners for the event.
110
Modeling
2.7.3.8
Modifying Presentation of Components
To modify presentation properties of a form component, such as, its size, position, alignment, or possibly properties
for custom form component, use presentation hints. Availability of hints depends on the component type. The hint
value is defined as a string with an expression.
Note that it is the component implementation that must process the hint, for the hint to be applied.
Implicit hint values depend on the component type. The hints are defined in the ui::ui.hints file in the
Standard Library.
2.7.3.8.1
Assigning Hints
You can assign a presentation hint to a form component in the following ways:
• Select a hint defined in a hint definition file.
• Assign a hint defined as an expression.
Important: Any hint assigned to a component is inherited by its child components. Note that some
hints are defined implicitly and are not visible in the Form editor; for example, layout components have
their width set to 100% by default and their children therefore have the width set to 100% as well. To
ignore inherited hint values, override the hint value on the child component with another value or the
null value if you want to erase the value.
2.7.3.8.1.1
Assigning Hints Defined in the Hints Definition File
To assign a form component a hint from a hint definition file, do the following:
1. In Form editor, select the form component.
2. In its Properties view, select the Presentation Hints tab.
3. Display the Hint Table tab.
4. Click the Add button to create a new hint or select an existing hint in the table and click Edit.
5. In the Edit dialog window, define the hint properties:
(a) In the Hint name text field, select a predefined hint in the drop-down menu. You can also enter a hint
name manually even if the hint is not defined in a hint definition file.
Note that the hints available in the drop-down list by default are the hints defined in the ui::ui.←hints file in the Standard Library. To create your own custom hints, create a hints definition and define
your hints in the file.
(b) In the Hint description area, provide optional arbitrary description.
(c) Either select a predefined hint value in the Predefined option drop-down or define its value in the Expression text area.
2.7.3.8.1.2
Applying Hints Defined as an Expression
To define a hint as an expression and have it applied on a form component, do the following:
1. In Form editor, select the form component.
2. In its Properties view, select the Presentation Hints tab.
3. On the Additional Hints tab click Edit.
4. Define the hint name and values as a map of a String and Object (for example, ["myhint" -> "My
Hint Value" + varString]).
2.7 Forms
2.7.3.8.2
111
Aligning Components
To define alignment of child components in the Vertical, Horizontal, and Grid Layout, and Table Column, use the
align hint. Note that the top, middle, and bottom align settings are simply ignored.
On a Table Column, the alignment is applied also on the column header. If necessary, you can override the setting
with the header-align hint.
2.7.3.8.3
Resizing Components
Component size is defined by the height and width component hints. Where applicable, the size hints are defined
implicitly. However, you can be override them with an explicit hint definition.
Hint values can be defined in the following units:
• font-relative units: size definition relative to the font size
– em: size in factors of the letter m size
– ex: size in factors of the letter x size
• absolute size: component size in pixels (px), picas (pc), points (pt), mm, cm, or inches (in)
• relative size to the parent: component size in relation to the size of the immediate parent
You can use the predefined values:
– fillparent: identical to 100%,
– wrapcontent: component size is set to the sum of sizes of children components
• expand: Sets the expand ratio for a component. If there is only one component with an expand ratio, the
component will be expanded to the maximum possible size within its parent. This hint can only be applied to
a table Column or the direct child of a Vertical or Horizontal Layout. From Layout is unsupported.
2.7.3.8.3.1
Defining Maximum Text Size on TextBox and TextArea
The TextBox and TextArea components can define the max-text-size hint, which defines the maximum length of the
text the user can enter. If the component is bound to a shared record field, the size must take into account the size
of the underlying database column, that is the column to which the field is mapped.
You can hence generate the hint for TextBox and TextArea components that are bound to shared record fields. Note
that the hint generation is applied on all open GO-BPMN projects of your workspace. Close any projects you want
to exclude.
To generate or adjust the max-size-hint for all TextBox and TextArea components in all open GO-BPMN projects, do
the following:
1. Got to Project Update max-text-size hint.
2. In the Update max-text-size hints dialog, select the applicable choices:
• Add missing max-text-size hint to generate the hint on any TextBox and TextArea components bound to
a shared record field if the hint is missing
• Update existing max-text-size hints to overwrite any defined values of the hint with the database column
sizes
Important: If a max-text-size hint contains a non-integer value, the hint is invalid. For such hints the
invalid value is retained and a dialog box with a notification about such a value is displayed.
• Ignore if value of max-text-size hint is smaller than DB length to prevent overwriting of the field length
that are smaller than the length of the underlying database column size.
112
Modeling
2.7.3.8.3.2
Default Size Hint Values
Form components define implicitly presentation hints with default values. These values are applied unless you
define another value for the hint.
Note that the default values might be in conflict. As a result, the rendered form might not meet your requirements or
render at all. For example, consider a table in a vertical layout:
• Vertical layout has the default width hint defined to wrapcontent so it checks the size of its child components and sets its width to the maximum child width.
• A table has the default width hint value defined as fillparent so it uses the parents' width.
Hence there is no setting for the table or the layout and you need to explicitly set to one of the widths to a required
value.
Default Widths and Heights
Component
Default Width
Default Height
Container Components
fillparent
wrapcontent
Grid Layout
fillparent
wrapcontent
Form Layout
fillparent
wrapcontent
Text Box
wrapcontent
wrapcontent
Text Area
wrapcontent
wrapcontent
Check Box
wrapcontent
wrapcontent
Combo Box
wrapcontent
wrapcontent
Lazy-Loading Combo Box
wrapcontent
wrapcontent
Form Layout
fillparent
wrapcontent
Single-Select List
wrapcontent
wrapcontent
Multi-Select List
wrapcontent
wrapcontent
Check-Box List
wrapcontent
wrapcontent
Radio-Button List
wrapcontent
wrapcontent
File Upload
wrapcontent
wrapcontent
Output Text
fillparent
wrapcontent
Table
wrapcontent
wrapcontent
Calendar
fillparent
fillparent
Action Button
wrapcontent
wrapcontent
Browser Frame
fillparent
wrapcontent
Button
wrapcontent
wrapcontent
Cartesian Chart
fillparent
400px
Gauge Chart
fillparent
400px
Pie Chart
fillparent
400px
Polar Chart
fillparent
400px
Conditional
fillparent
wrapcontent
Dashboard
fillparent
fillparent
Dashboard Widget
0, 0, 200, 300
overrides DashBoard
File Download
wrapcontent
wrapcontent
Geolocator
Horizontal Layout
invisible
wrapcontent
invisible
wrapcontent
Image
wrapcontent
wrapcontent
Lazy Table
wrapcontent
wrapcontent
2.7 Forms
2.7.3.8.4
113
Component
Default Width
Default Height
Tree Table
wrapcontent
wrapcontent
Map Display
fillparent
400px
Message
fillparent
wrapcontent
Navigation Link
wrapcontent
wrapcontent
Panel
fillparent
wrapcontent
Popup
fillparent
wrapcontent
Repeater
wrapcontent
wrapcontent
Tabbed Layout
fillparent
wrapcontent
Table Column
counted by the table
counted by the table
Tree
wrapcontent
wrapcontent
Vertical Layout
fillparent
wrapcontent
View Model
fillparent
wrapcontent
Component Presentation
With the html-class hint, you can define the presentation of any component, such as, border rendering, highlighting, emphasis, overflow, disabling of text, etc. Refer to the hints documentation in the Standard
Library documentation.
2.7.3.8.4.1
Adding a CSS Class
To add a class attribute to the rendered component, use the html-class hint.
Note that the class must be defined in the Process Application. For instructions on how to add new style sheets,
refer to Custom Process Application Guide.
2.7.3.8.4.2
Adding an Awesome Icon
To add an icon from the Awesome font to your component class, assign the icon presentation hint to your component and insert the name of the icon as its value.
114
Modeling
2.7.3.8.5
Creating Hint Definitions
Hints can be defined either ad-hoc directly on a form component or in a hints definition file. The hints defined in a
hints definition file are available in the entire parent module.
To define hints that can be used by all forms in the module, do the following:
1. Create a hint definition file (go to File New Hint Definition, and select the parent module and provide the
definition file name).
2. In the GO-BPMN Explorer, double-click the hint definition file. By default, the file opens for editing in the
built-in Hint Editor.
3. In the Hint Editor, click the Add button.
4. On the right, define the hint properties:
• Name: hint name displayed in the Hint name drop-down menu.
• Component: comma-separated list of form components that can use the hint
• Hint options: value options available for the hint in the Predefined option (the label holds the displayed
name of the option and the expression holds the value it is translated to when rendered)
Figure 2.85 Hints editor with a hint definition
2.7.3.9
Creating Mobile Forms
LSPS provides support for creating mobile forms that can be used in mobile LSPS applications.
Important: A mobile LSPS application is by no means intended to substitute the desktop application
and should be considered an extension of the desktop application.
The specific support for mobile forms in LSPS includes the following:
• mobile presentation hint for the vertical and horizontal layout component
2.7 Forms
2.7.3.9.1
115
Guidelines
• Use horizontal layout with the mobile hint only to hold a set of buttons.
• Wrap more complex forms either in the vertical layout component with the mobile hint or in the Tabbed
container component. Every Tab component can then contain a part of the form. In the Tab component, use
preferably icons instead since the used font is rather small.
• Do not nest a layout component with the mobile hint into another layout component with the mobile hint. The
exception is a horizontal layout component with buttons.
• Adapt your forms to different screen sizes and resolutions: use Conditional components with different "versions" of the form.
To detect the screen size on runtime do the following:
– Create the custom getBrowserWindowWidth() that returns an Integer. The function is implemented as the getBrowserWindowWidt() method in com.whitestein.lsps.app.vaadin_←touchkit.touchkit.MobileUtils and returns the width of the displayed page in DP(density
independent pixel).
– Define how to handle the ApplicationEvent with the ID internal_windowresize. The event is
produced when the width of the browser window changes and therefore also when the device is rotated.
It bears the window size in DP as its payload (held by the ui::Dimension record instance).
Important: If the user provides invalid values in the form and the window width changes, the invalid
values are not transferred to the refreshed form. Consider handling such situations in your form.
2.7.4
Component Reference
• Container Components
• Input Components
• Output Components
• Action Components
• Special Components
• Annotations
• Deprecated Components
2.7.4.1
Container Components
Container components nest components and define the form structure.
They can fire only InitEvents with the exception of the Dashboard Widget, which can fire a WidgetChangeEvent as
well.
2.7.4.1.1
Vertical Layout
The Vertical Layout component (
arranged in a vertical manner.
) is a container component that can hold multiple form components, which are
Specific Vertical Layout properties:
• Label: object that is displayed as the title of the layout; label is rendered by the parent component; hence the
layout is the root component, Label is not rendered.
116
Modeling
2.7.4.1.2
Horizontal Layout
The Horizontal Layout component (
are arranged in a horizontal manner.
) is a container component that can hold multiple form components, which
Specific Horizontal Layout properties:
• Label: object that is displayed as the title of the layout; label is rendered by the parent component; hence the
layout is the root component, Label is not rendered.
2.7.4.1.3
Form Layout
The Form Layout component (
) is a container component that can hold multiple form components arranged
in two columns. The child form components are rendered with their labels placed in the left column and any other
component parts rendered in the right column.
Figure 2.86 Form with multiple Form Layouts
2.7.4.1.4
Panel
The Panel component (
a layout, component.
) is a container component that serves for adding a frame and a caption to one, possibly
A scrollbar is rendered in panel child components automatically if applicable.
Figure 2.87 Asset Table nested in a collapsible panel (note the collapse box next to the table label)
The Panel component has the following properties:
2.7 Forms
117
• Title: label displayed on the panel The Title property supports HTML content.
• Collapsed: if set to true, the panel is rendered as collapsible
2.7.4.1.5
Grid Layout
The Grid Layout component (
) is a container component that can hold multiple form component elements, which
are arranged in a grid manner, that is in a table-like way. You can add rows and columns to the grid using the Add (
) and Delete (
) buttons on the grid component.
Figure 2.88 Grid Layout component
2.7.4.1.6
Tabbed Layout
The Tabbed Layout component (
2.7.4.1.6.1
) is a container component that can hold multiple Tab components.
Tab
The Tab component (
) is a component rendered as a tab. It that can contain one form component and its parent
component must be the tabbed layout component.
A tab content and its children are initialized along with their parent. However, a tab produces an init event and is
refreshed when displayed.
The Tab component has the following properties:
• Title: tab label
• Visible: boolean expression defining the tab visibility
If the visible expression evaluates to true or undefined on init or refresh, the tab is displayed.
Note that you can add, remove, and select a Tab component programatically from listener handle expression using
the addTab(), removeTab(), selectTab() functions.
118
Modeling
2.7.4.1.7
Container
) is a form component that allows you to define an interface for a form or a form
A Container component (
component and its child components. The interface provides a mechanism for listening for events either on nested
forms or on parent forms (for details refer to Container Interface).
2.7.4.1.8
Popup
The Popup component (
) rendered as a pop-up window with a maximize/minimize and close button in its
caption. It can be modal: when a model popup is displayed, you cannot work with the underlying form until it is
closed.
Since Popups are included directly in the form, they are calculated when the form is initialized. For large popups
with a lot of data, this can result in poor form performance since these popups are part of the form all the time even
if you might not need them at all. In such a case, consider using a dynamic popup which is created only when
requested.
For an example popup design and usage, refer to Pop-up with Apply and Cancel Buttons.
2.7.4.1.8.1
Dynamic Popup
Dynamic popups are created at the moment they are requested. This prevents existence of potentially unnecessary
Popups in the form hierarchy: this can save you some headache over performance of your form.
To design a dynamic popup, do the following:
1. Create a form with a component that will create your popup or a reusable form: To create the popup when an
action occurs, call the function createAndShow() from a Listener handle expression of the component:
define the logic of the popup, possibly using clear() and merge() functions. To remove the popup from
the component tree, call the hideAndDestroy() function on the popup.
1
2
3
4
5
6
//This creates a popup possibly from the handle of of a listener:
def ui::Popup popup := new ui::Popup( visible -> {-> false} );
//child is a form that takes arguments what data to work with, what component to refresh,
//and the popup so it can close it:
popup.child := formWithPopupContent(&newData, VL_MAIN, popup);
createAndShow(popup);
Note that you can use functions from the dynamics.funcs file in the ui module to search for components higher or
lower in the hierarchy, for example, findTopmostComponents(), findTopmostContainers(), get←Children(), etc.
2.7.4.1.8.2
Closing a Popup
You can close a popup by setting its visibility to false and refreshing it from any listener so it disappears or with the
hideAndDestroy() function on the popup.
If you want to close your popup with an X button in its caption, define the previously described behavior in the
popups PopupCloseRequestListener.
2.7 Forms
2.7.4.1.9
119
Dashboard
The Dashboard component
is a container component that can hold multiple widget components.
When working with a rendered dashboard in the client application, use the plus (+) button on the dashboard to
display a widget. Visualized widgets can be positioned anywhere within the dashboard, resized, and visualized as
necessary. Only one instance of the given widget can be visualized on the dashboard.
Note that dashboard has a toolbar, which can contain any form element apart from a widget.
Figure 2.89 Form with a Dashboard component
Note: By default, dashboard size adapts to the requirements of the visualized widgets with the minimum
size 650x490 px. To alter the size, use presentation hints on the dashboard (refer to the Standard
Library document).
2.7.4.1.9.1
Dashboard Widget
The Dashboard Widget component
is a form component that is rendered as a widget on a dashboard: Therefore
it must have the Dashboard component as its parent. A Dashboard Widget can hold one form component.
It produces events of the following types:
• InitEvent when the component is initialized or displayed if previously hidden
• WidgetChangeEvennt when the user add a widget to the dashboard, resizes, moves, or hides a widget
The event contains information on the widget properties in the WidgetConfiguration field.
By default, when a dashboard is visualized, it remains empty. The user can then add the available widgets to the
dashboard using the plus (+) button on the dashboard. To visualize a widget immediately when a dashboard is
displayed, define the widget’s Configuration property: the property is defined as its WidgetConfiguration property.
For example, if the Configuration property is set to new WidgetConfiguration(visible -> true,
width -> 300, height -> 300, top -> 300, left -> 350). The widget will be visible when
the dashboard is displayed; its size will be 300x300 pixels; the coordinates of the upper left corner will be 300:350
(its upper left corner will be positioned 300 pixels below the top of the dashboard and 350 pixels to the right).
The Dashboard Widget component has the following properties:
120
Modeling
• Title: widget title
• WidgetID: ID used in the WidgetChangeEvent
• Configuration: WidgetConfiguration object defining the visualization properties of the widget when the dashboard is visualized
WidgetConfiguration defines the following:
– visibility: boolean value that defines whether the widget is displayed by default when the dashboard is displayed
In the default Process Application, previously closed or invisible widgets can be visualized by clicking
them under the + plus button of the dashboard.
– width: default width of the widget
– height: default height of the widget
– top: distance of the top widget border from the dashboard top border
– left: distance of the left widget border from the dashboard left border
– zIndex: vertical stacking order of the widget
When the widget produces a WidgetChangeEvent, that is whenever it is clicked, moved, or resized, the
zIndex is raised so that the widget is on top of any other widgets in the dashboard.
– maximized: boolean value that defines if the widget is maximized
– minimized: boolean value that defines if the widget is minimized
In the default Process Application, minimized widgets are available in the toolbar of the dashboard.
Note: Note that widgets keep its last size value separate from its maximized and minimized status←: if you set a widget to a particular size, then maximize it, and minimize it, when restored it will be
maximized. If you then double-click the widget caption, it will be restored to the original size. If you
want to move a widget to the foreground, click the widget.
Figure 2.90 Dashboard with Widgets
2.7 Forms
2.7.4.2
121
Input Components
Input components serve to acquire input for the user: When the user provides the input, the component produces
a value change event, which can be caught by a value change listener. The listener may define further actions to
process the event. The actions are taken during the next response-request cycle.
When the user provides the input or changes the content of an input component, the component produces a value
change event, which can be caught by a value change listener. The event is by default not immediate, which means
it does not trigger a response-request cycle. However, if the input component has its property Immediate set to
true, such events do trigger the cycle.
Note: When you change a value in an input component, the value change is applied on the bound entity,
such as, a variable, even if no listener for the value change event exists. To prevent this behavior, use
nested contexts.
2.7.4.2.1
Text Box
The Text Box component (
) is rendered as single-line text field to allow the user to provide text input.
It produces events of the following types:
• InitEvent when the component is initialized or displayed if previously hidden
• ValueChangeEvent when the component has changed content and loses focus (to process it also on focus
loss; set the Immediate property to true)
• ActionEvent when the user presses ENTER while the Text Box is focused
• AsynchronousValueChangeEvent whenever the user inserts or removes a character
Note that the binding of the Text Box does not have to change immediately due to possible validation; hence
binding of the Text Box might appear out-of-date.
The Text Box component has the following properties:
• Label: visible text label
• Placeholder: input prompt (text displayed in the text box if the value of the Binding reference is null)
• Required: compulsoriness of the field
If true, a mark indicating that the field is required is rendered in the component. Note that the property does
not provide any validation. The validation must be implemented on the respective listener, possibly as a
validation expression.
• Binding: reference to a slot that holds the text value (for example, a form variable or global variable)
If a Text Box binds to a Date type, it is rendered as the Date Picker: for the Date Picker you can define the
format of the date the Date Picker will accept in the Format property. The available formats are defined in the
additional∗formats hint.
• Format: required input format, such as, date, integer, etc.
The format can be specified as defined in java.util.Pattern, java.text.SimpleDateFormat, and java.text.←DecimalFormat
If the value in the field is not of the defined format pattern, a validation mark is displayed next to the Text Box.
Note that the property does not provide any validation. The validation must be implemented on the respective
listener possibly as a validation expression.
• Read-only: editability of the text
If true, the text renders as grayed out and cannot be edited.
• Immediate: setting of the Immediate mode
If true, the immediate mode is active: the value change event triggers request-response cycle on focus
change.
• Help text: tooltip text
122
Modeling
2.7.4.2.1.1
Defining Suffix on a Text Field
To add a suffix to a Text Field component, such as, PCS, define on the Text Field the suffix Hints with the value of
the suffix in a String. You can do so on the Presentation Hints tab of the Properties view.
2.7.4.2.2
Text Area
The Text Area component (
) renders as multi-line text input Area to allow the user to provide longer text input.
It produces events of the following types:
• InitEvent when the component is initialized or displayed if previously hidden
• ValueChangeEvent when the component contains changed content and loses focus (to process it also on
focus loss; set the Immediate property to true)
• AsynchronousValueChangeEvent whenever the user inserts or removes a character
Note that the binding of the Text Area does not have to change immediately due to possible validation; hence
binding of the Text Box might appear out-of-date.
The Text Area component has the following properties:
• Label: visible text label
• Placeholder: input prompt (text displayed in the text area if the value of the Binding reference is null)
• Required: whether the area is required
If true, a mark indicating that the area is required is rendered in the component. Note that the property does
not provide any validation. The validation must be implemented on the respective listener, possibly as a
validation expression.
• Binding: reference to a slot that holds the text value (for example, a form variable or global variable)
• Read-only: editability of the text
If true, the text area is grayed out and cannot be edited.
• Immediate: setting of the Immediate mode
If true, the immediate mode is active: the value change event triggers request-response cycle on focus
change.
• Help text: tooltip text
2.7.4.2.3
Check Box
The Check Box component (
value.
) renders as a check box with a Label and allows the user to provide a Boolean
It produces events of the following types:
• InitEvent when the component is initialized or displayed if previously hidden
• ValueChangeEvent when the component was selected or unselected (to process it also on focus loss; set the
Immediate property to true
The Check Box component has the following properties:
2.7 Forms
123
• Label: visible check box labe to trigger the event-processing cycle
• Required: compulsoriness of the check box
The property is not applicable for Check Box components.
• Binding: reference to a slot that holds the Boolean value (for example, a form variable or global variable)
• Read-only: editability of the check box
If true, the check box renders as grayed out and cannot be edited.
• Immediate: setting of the Immediate mode
If true, the Immediate mode is active: any value changes on the check box are processed immediately
• Help text: tooltip text
2.7.4.2.4
Combo Box
The Combo Box component (
) renders as a single-line text field with a drop-down list of options with the
possibility to insert a non-listed option.
It produces events of the following types:
• InitEvent when the component is initialized or displayed if previously hidden
• ValueChangeEvent when the user selects an option (to process it at this point, set the Immediate property to
true
The Combo Box component has the following properties:
• Label: visible label
• Placeholder: input prompt (text displayed in the text field if the value of the Binding reference is null)
• Required: compulsoriness of the combo box
If true, a mark indicating that the value is required is rendered in the component. Note that the property
does not provide any validation. The validation must be implemented on the respective listener possibly as a
validation expression.
• Binding: reference to a slot that holds the selected option value (for example, a form variable or global
variable)
• Read-only: editability of the combo box
If true, the combo box renders as grayed out and no option can be displayed or selected.
• Immediate: setting of the Immediate mode
If true, the Immediate mode is active: any value changes on the combo box are processed immediately.
• Options: list of options
The list items are displayed in the drop-down. Make sure the defined expression resolves to an object of type
List<ui::Option>.
Note that the Option data type has the value and label field so that you can define the label displayed in the
drop-down list that represents the given value.
∼∼ collect(literals(type(AssetType)), {e -> new ui::Option(value -> e, label -> literalToName(e))}) ∼∼
• Create new option: closure that is called if the user enters a custom value
When the user enters a custom value in the text field of the combo box, the closure is called with the value as
its parameter. The closure returns an object that is set to the binding value.
Important: A event that creates a new option is created only when the user presses ENTER after they
input the new value.
• Help text: tooltip text
124
Modeling
2.7.4.2.5
Lazy-Loading Combo Box
component renders as a single-line text field with a drop-down option list. HowThe Lazy-Loading Combo Box
ever, the options in the drop-down are paged and queried as the user enters parts of the option so the component
is useful if you need to select one item from many options.
It produces events of the following types:
• InitEvent when the component is initialized or displayed if previously hidden
• ValueChangeEvent when the user selects an option (to process it also at this point; set the Immediate property
to true
When creating a Lazy-Loading Combo Box component, define the following properties:
• Label: visible label
• Required: compulsoriness of the combo box
If true, a mark indicating that the value is required is rendered in the component. Note that the property
does not provide any validation. The validation must be implemented on the respective listener possibly as a
validation expression.
• Binding: slot that holds the selected option value, such as a form or global variable
• Read-only: editability of the combo box
If true, the combo box renders as grayed out and is disabled.
• Immediate: setting of the Immediate mode
If true, the Immediate mode is active: when the user selects an option, the event is processed immediately.
• Options: list of options
The closure returns a List<Object>, where each list object represents an option. What is actually displayed
as a label for the option is defined in the Formatter property.
The closure has the following input parameters:
– value in the text field (the value is a String and can serve to filter out the options in the drop-down list)
2.7 Forms
125
Figure 2.91 Lazy-Loading Combo Box with no value in the text field
– index of the first option (options of items starting from this index can be displayed)
– displayed option count (the number of options from the first option to be displayed)
• Option count: count of displayed options
Make sure the defined closure returns an Integer value. Typically you want to use a count query.
1 {code -> getCurrencies_count(code, null, null)}
• Formatter: closure that returns a string that is displayed in the drop-down list
The string represent the respective object from the Options.
1 {c:Currency -> c.currencyCode}
• Create new option: closure that is called when the user enters a custom value
If the user enters a custom value in the combo text field of the combo box, the closure accepts the value as
its parameter and returns it to the binding entity.
• Placeholder: input prompt (text displayed in the text field if the value of the Binding reference is null)
• Visible: whether the component is displayed (if not, the component is not initialized)
• Help text: tooltip text in the Help Text tab
126
Modeling
2.7.4.2.5.1
Creating a Lazy-Loading Combo-Box
Typically, a lazy-loaded combo box offers the available options as the user inputs characters: in the background, the
options need to be loaded in batch required by the combo box.
Figure 2.92 Lazy-Loading Combo Box with options for the user input
To create such a lazy-loading combo box, do the following:
1. Define the Binding property with the target slot for the selected option.
2. Define the Options property so that the closure returns the results for what the user typed into the combo box.
The user input is passed as the first closure parameter.
1 {userInput, firstPageItem, batchSize -> getCurrenciesContaining(userInput, firstPageItem, batchSize)}
In the example above, the query is defined so as to return:
• only results that contain the user input, for example, you can define a query with a condition, such as,
currentCurrency.code like userInput +"∗"
• and that in batches defined by the closure input parameters firstPageItem and batchSize
3. Define the Options count property so that the closure returns the number of options returned by the Options
property.
1 {userInput -> getCurrenciesCountForFiltered(userInput)}
Consider using the count query to obtain the options count.
4. Define the Formatter property so that it returns the string displayed in the drop-down menu.
1 { c:Currency -> c.code }
5. Define the Placeholder property with the string that should be displayed if no option is selected. Alternatively,
in the Formatter property handle the object for null value.
2.7 Forms
2.7.4.2.6
127
Single Select List
The Single Select List component (
select exactly one option.
) is a form component that displays a list of options and allows the user to
It produces events of the following types:
• InitEvent when the component is initialized or displayed if previously hidden
• ValueChangeEvent when the user selects an option (to process it also, set the Immediate property to true)
Figure 2.93 Single Select List in a Panel
• Label: visible label
• Required: compulsoriness of the list
If true, a mark indicating that the value is required is rendered in the component. Note that the property
does not provide any validation. The validation must be implemented on the respective listener possibly as a
validation expression.
• Binding: reference to a slot that holds the selected option value (for example, a form variable or global
variable of the respective type)
• Options: list of options
The options are displayed as a vertical list. Make sure the defined expression resolves to an object of type
List<ui::Option> object.
Note that the Option data type has the value and label field so that you can define the label displayed in the
drop∗down list that represents the given value.
128
Modeling
• Read-only: editability of the Single Select List
If true, the list renders as grayed out and no option can be selected.
• Immediate: setting of the Immediate mode
If true, the Immediate mode is active: any value changes are processed immediately.
Important: An event that creates a new option is created only when the user presses ENTER after
they input the new value.
• Help text: tooltip text
2.7.4.2.7
Multi Select List
The Multi Select List component (
select multiple options.
) is a form component that displays a list of options and allows the user to
It produces events of the following types:
• InitEvent when the component is initialized or displayed if previously hidden
• ValueChangeEvent when the user selects an option (to process it also, set the Immediate property to true)
Figure 2.94 Multi Select List
2.7 Forms
129
• Label: visible label
• Required: compulsoriness of the multi-select list
If true, a mark indicating that the set of selected values is required is rendered in the component. Note that
the property does not provide any validation. The validation must be implemented on the respective listener
possibly as a validation expression.
• Binding: reference to a set of objects that holds the selected values
• Options: list of options
The list is displayed in the drop∗down menu. Make sure the defined expression resolves to an object of type
List<ui::Option>.
• Read-only: editability of the Multi Select List
If true, the list renders as grayed out and no option can be selected.
• Immediate: setting of the Immediate mode
If true, the Immediate mode is active: any value changes are processed immediately.
• Help text: tooltip text
2.7.4.2.8
Check Box List
The Check Box List component is a form component that displays a list of options with check boxes and allows the
user to select multiple options using the check boxes.
It produces events of the following types:
• InitEvent when the component is initialized or displayed if previously hidden
• ValueChangeEvent when the user selects an option (to process it also at this point, set the Immediate property
to true)
130
Modeling
Figure 2.95 Check Box List in a Panel component
• Label: visible label
• Required: compulsoriness of the check box list
If true, a mark indicating that the set of selected values is required is rendered in the component. Note that
the property does not provide any validation. The validation must be implemented on the respective listener
possibly as a validation expression.
• Binding: reference to a set of objects that holds the option values
• Options: list of options
The list is displayed as entries in the check list. Make sure the defined expression resolves to an object of
type List<ui::Option> object.
• Read-only: editability of the Check Box List
If true, the list renders as grayed out and no option can be selected.
• Immediate: setting of the Immediate mode
If true, the Immediate mode is active: any value changes are processed immediately.
• Help text: tooltip text
2.7.4.2.9
Radio Button List
The Radio Button List component is a form component that displays a list of options and allows the user to select
exactly one option by clicking a radio button.
It produces events of the following types:
2.7 Forms
131
• InitEvent when the component is initialized or displayed if previously hidden
• ValueChangeEvent when the user selects an option (to process it also at this point, set the Immediate property
to true)
Figure 2.96 Radio Button List in the Panel component
• Label: visible label
• Required: compulsoriness of the Radio Button List
If true, a mark indicating that the set of selected values is required is rendered in the component. Note that
the property does not provide any validation. The validation must be implemented on the respective listener
possibly as a validation expression.
• Binding: reference to a slot that holds the selected option value (for example, a form variable or global
variable of the respective type)
• Options: list of options
The options are displayed as a vertical list with radio buttons on the left. Make sure the defined expression
resolves to an object of type List<ui::Option>.
• Read-only: editability of the Radio Button List
If true, the radio button list renders as grayed out and no option can be selected.
• Immediate: setting of the Immediate mode
If true, the Immediate mode is active: any value changes are processed immediately.
• Help text: tooltip text
132
Modeling
2.7.4.2.10
Token Field
) serves for selection of multiple options. Whenever the user selects or removes
The Token Field component (
an option, the component fires a ValueChangeEvent.
The component is rendered by default as a combo box, so the user can click the arrow on the combo box to display
the options. However, you can render the Token Field as a Text Field by setting its html-class presentation hint
to tokentextfield.
• Label: visible label
• Required: input compulsoriness
If true, a mark indicating that the set of selected values is required is rendered in the component. Note that
the property does not provide any validation. The validation must be implemented on the respective listener
possibly as a validation expression.
• Binding: reference to a slot that holds the selected options (typically a form variable of the collection type
that holds the same type as the option value, for example, Set<String>)
• Read-only: editability
If true, the radio button list renders as grayed out and no option can be selected.
• Immediate: setting of the Immediate mode
If true, the Immediate mode is active: any value changes are processed immediately.
• Options: list of options
The options are displayed when the user start entering character that appear in on of the option values
1 collect(1..10, { x:Integer -> new Option(label -> "Option " + x, value -> "Value " + x) })
• Visibility: whether the component is visible or hidden
• Help text: tooltip text
Note: You can define the Help text on the Help Text tab in the Properties view.
2.7.4.2.11
Tree
The Tree component (
) serves as a picker of one node from a tree. Once the user selects a node, the selection
is stored in the Binding slot.
The nodes are expandable unless they are leaf nodes, that is, they do not have any children. Whenever a node is
expanded its child nodes are lazy-loaded. The Tree component calls the closure defined in the Children property to
acquire child nodes if children in a Root element are null. The closure returns a collection of <TreeItem> objects.
It produces events of the following types:
2.7 Forms
133
• InitEvent when the component is initialized or displayed if previously hidden
• ValueChangeEvent when the user selects an option (to process it also at this point, set the Immediate property
to true)
Figure 2.97 Tree with Multiple Nodes Expanded
The Tree component has the following properties:
• Label: visible label
• Required: compulsoriness of the tree component; If true, a mark indicating that the value is required is
rendered in the component.
Important: The property does not provide any validation whether the field contains a value and
the user will be able to submit a null value unless a additional validation mechanism is defined.
Such a validation can be implemented on a listener, possibly as a validation expression.
• Binding: reference to a slot that holds the selected tree option value (for example, a form variable or global
variable)
• Root: collection of TreeItem that are root items of the tree
• Children: closure that returns a list of tree items which are displayed when a node is expanded
1 { parent:Position, depth:Integer ->
2
compact
3
(collect(
4
positions, {
5
p:Position -> p.parent=parent ? new TreeItem (
6
data ->p, expanded ->false, label ->p.name) : null}))
7 }
• Read-only: editability
If true, the tree renders as grayed out and no option can be selected. The selection uses the value of the
binding slot.
• Immediate: setting of immediate mode (If true, the Immediate mode is active: any value changes on the tree
are processed immediately)
• Help text: tooltip text
134
Modeling
2.7.4.2.12
File Upload
The File Upload component allows the user to upload a file to the server. It renders as an input field for a file path
and a Browse and upload button.
Figure 2.98 File Upload
It produces events of the following types:
• InitEvent when the component is initialized or displayed if previously hidden
• ValueChangeEvent when the user selects an option (to process it also at this point, set the Immediate property
to true)
• FileUploadEvent produced on file-upload completion
Since file upload is an asynchronous process, on runtime, the component produces an ActionEvent when the upload
button is clicked and an FileUploadEvent when the uploading finishes.
Figure 2.99 File Upload
• Label: visible label
• Required: compulsoriness of the file upload
If true, a mark indicating that the value is required is rendered in the component. Note that the property
does not provide any validation. The validation must be implemented on the respective listener possibly as a
validation expression.
• Binding: reference to a set of objects that will hold the files
• Read-only: editability of the File Upload
If true, the component is disabled and grayed out and no file can be selected.
• Immediate: setting of the Immediate mode
If true, the Immediate mode is active: any value changes are processed immediately.
• Button text: label of the upload button
• Multiple: setting for enabling upload of multiple files
2.7 Forms
135
Important: This option is currently not supported since native HTML forms do not allow selecting
multiple files in one window.
• Upload to memory: target where the file is uploaded
If true, the file is uploaded to memory. If false, the file is uploaded to LSPS_BINARY_DATA table in the
application database.
• Delete temp data: if true, the files from the LSPS_BINARY_DATA are deleted when the respective HTTP
session finishes (applicable only if Upload to memory is set to false)
• Help text: tooltip text
2.7.4.3
Output Components
Output components serve to display data in a certain way and include the following:
• Output Text
• Tabular Components
• Grid
• Repeater
• Image
• Navigation Link
• File Download
• Pie Chart
• Gauge Chart
• Cartesian and Polar Chart
• Browser Frame
• Calendar
• Map Display
2.7.4.3.1
Output Text
The Output Text component is rendered as read-only, single-line text field.
• Label: object that is displayed as label of the output box
• Content: object that is displayed in the output box
• Format: formatting applied on the object defined in the Content property defined as a String
The applicable format depends on the data type of the object from the Content property:
– Format for a Date, Decimal, or Integer object can defined following Java format standards:
* Date: java.text.SimpleDateFormat
* Integer: java.text.DecimalFormat
* Decimal: java.text.DecimalFormat
– Format for a String, the Format property can be set to:
* html: HTML tags are supported.
* plaintext: Line breaks in the Content object are ignored.
* preformatted: Line breaks are respected.
– Any objects of other types are transformed with the toString() function and no Format setting
applies.
136
Modeling
2.7.4.3.2
Tabular Components
Tabular components include the Table and Tree Table components which share common features: they serve to
display data in a tabular manner and have the Column components as their immediate children. Both work with the
same types of data sets and support ordering and filtering of their content.
2.7.4.3.2.1
Table
The Table component displays the data of its data set in the child components of the table's columns: The system
iterates through individual objects of the data set and each object becomes the data iterator value for a row. The
iterator is then used by the child components of table columns to access the data object.
It supports ordering, filtering, and grouping of the data.
The way the data set is acquired and the way the table is rendered is defined by the table type:
• simple: The table is on one page and the data obtained in a single request.
• lazy: The table is rendered with a particular size and with a scroll. The data is loaded as the user scrolls
through the table.
• paged: The table is rendered with a page navigation at the bottom. The data is acquired per page.
The data set itself can be defined as the following:
• Type: shared record or a shared record field
The system fetches all shared record instances from the database.
• Query: query that returns a collection of objects
The table iterates through the collection objects.
• Collection: collection of the data object
The table iterates through the collection objects.
• Data: parametric closure that returns the collection of data objects
The first parameter holds the index of the first entry; The second parameter is the count of entries per load or
page. You will use this option typically when integrating with other systems, for example, {currentIndex,
count -> getEntryBatch(currentIndex, count)}.
This data kind requires the Data count property, expression that returns the total amount of entries to be
loaded.
• Generic: an Object that results in any of the above on runtime
The setting is used for generic reusable tables when the user wants to fill the same table with different data
queried in different ways, typically when reusing the form in other forms.
2.7.4.3.2.2
Creating a Simple Table
A simple Table is rendered as a table on a single page with all its items.
To create a simple Table, do the following:
1. Insert the Table component in a Form.
2. On the Details tab of the Properties view, define the following:
• Data Kind: data source type and the related data
• Data Iterator: reference to a local form variable of the same type as your Data objects.
Important: The data iterator can be used solely as the table iterator: using the iterator out of
the Table results in a validation Error.
• Type: TableType.simple
3. Insert Table Columns into the Table.
4. Into each column, insert the required components and bind them to the iterator data.
2.7 Forms
2.7.4.3.2.3
137
Creating a Paged Table
A paged table is rendered with on pages with the number of rows defined by the initial-page-size presentation hint
and page navigation at the bottom. It can be set to load a particular page using the Show Index property.
A paged table produces the TablePageSizeChangeEvent when the user changes the size of the table page.
To create a paged Table, do the following:
1. Select the Table component in a Form.
2. On the Details tab of the Properties view, define the following:
• Data Kind: data source type
– Type: shared record or a shared record field
– Query: query that returns a collection of objects
– Collection: data set is defined as a collection
– Data: parametric closure that returns a collection of table objects
The first parameter holds the index of the first entry. The second parameter is the count
of entries per load or page, for example, {currentIndex, count -> getEntry←-
Batch(currentIndex, count)}
– Generic: an Object that results in any of the above on runtime
• Type: TableType.paged
• Data Iterator: reference to a local form variable of a type that can hold your Data objects
Important: The data iterator can be used solely as the table iterator: using the iterator out of
the Table results in a validation Error.
• Show index: the index number of the page that should be opened on load.
• Index Iterator: reference to an object that will hold the index of the row where the current Data object is
used
3. Set the size of the page in the initial-page-size presentation hint.
4. Insert Table Columns into the Table.
5. Into each column, insert the required components and bind them to the iterator data.
2.7.4.3.2.4
Creating a Lazy-Loaded Table
A lazy table is rendered as scrollable table with the number of rows defined by the initial-page-size presentation
hint.
To create a Table, do the following:
1. Select the Table component in a Form.
2. On the Details tab of the Properties view, define the following:
• Data Kind: data source type
– Type: shared record or a shared record field
– Query: query that returns a collection of objects
– Collection: data set is defined as a collection
– Data: parametric closure that returns a collection of table objects
The first parameter holds the index of the first entry. The second parameter is the count
of entries per load or page, for example, {currentIndex, count -> getEntry←-
Batch(currentIndex, count)}
138
Modeling
– Generic: an Object that results in any of the above on runtime
• Type: TableType.lazy
• Data Iterator: reference to a local form variable of a type that can hold your Data objects
Important: The data iterator can be used solely as the table iterator: using the iterator out of
the Table results in a validation Error.
• Show index: the index number of the page that should be opened on load.
• Index Iterator: reference to an object that will hold the index of the row where the current Data object is
used
3. Insert Table Columns into the Table.
4. Into each column, insert the required components and bind them to the iterator data.
2.7.4.3.2.5
Defining Grouping on a Table
Groups serve to group the items in a table on multiple levels according to their properties in a tree-like way, for
example, a list of songs according to their interpret and then according to the album.
Note that grouping takes place on the data set and renders the table type setting irrelevant.
The groups are defined as a subtype of the abstract GroupSpec record and that as one of the following:
• PropertyGroupSpec: the groups are defined as Record properties;
1 [
2 //first-level grouping:
3 new PropertyGroupSpec (
4
label -> "Surname",
5
groupBy -> Author.surname),
6
//second-level grouping:
7
new PropertyGroupSpec
8
(label -> "First name",
9
groupBy -> Author.firstName)
10 ]
• ClosureGroupSpec: the groups are calculated on runtime in a closure;
1 [new ClosureGroupSpec(label -> "Surname", groupBy -> {a:Author -> a.surname})]
• OptClosureGroupSpec: the groups are calculated on runtime in a closure in optimized manner;
1 [
2 new OptClosureGroupSpec(label -> "Surname",
3
groupBy ->
4
{ c:Collection<Author > ->
5
def Set<String> surnames := toSet(collect(c, {a:Author -> a.surname}));
6
//creates map with surname as the key and collection of authors as value
7
map(surnames, {surname:String -> select(c, {a:Author -> a.surname == surname})})}
8
)
9 ]
Alternatively, if you are using the Type data kind, you can infer grouping: The system will "guess" the applicable
groups. The Group Spec then becomes a collection of all bindings of child components of all columns. Therefore,
grouping is inferred only on columns with one Input component with binding set to a simple data type entity.
To define grouping on a table, do the following:
1. In your form definition, select the table component.
2. In the Properties view, open the Grouping tab.
3. Uncheck Disable Grouping.
2.7 Forms
139
4. Define the grouping:
• For your own grouping:
(a) Define the GroupSpec and optionally Grouping that holds the currently applied grouping.
(b) Optionally, on individual table columns, define the Group value on their Grouping tab. The value is
used as a group header in the line that serves to expand and collapse the group.
1 {values:Collection<Author>->values[0].gender}
Figure 2.100 Form with Table and its Grouping Definition
• To infer grouping, select Infer Grouping.
140
Modeling
Figure 2.101 Setting Grouping
2.7.4.3.3
Grid
The Grid component displays single-line text data in a table layout and enables editing of the persistent data out-ofthe-box.
The Grid data is lazy-loaded, which prevents potential performance issues. Unlike in Tables, no Vaadin components
are created based on the content of cells: Grid columns do not contain components; they can only define how the
data is presented on the Grid Column components.
If you plan on using complex content, such as images, charts, etc. consider using Table.
Figure 2.102 Editable Grid with a validation message on incorrect value
2.7.4.3.3.1
Creating a Grid
To create a Grid with your content, do the following:
2.7 Forms
141
1. Insert the Grid component
into your Form.
2. In the Properties view of the Grid, define the data kind:
• Type: shared record or a shared record field
The Grid iterates over all shared record instances.
• Query: query that returns a collection of objects
The Grid iterates through the collection objects.
• Collection: data set is defined as a collection
The Grid iterates through the collection objects.
• Data: a collection of objects that are iterated through
When using queries to get the data, define the input parameters for index and entries count
and use them as paging definition, for example, {currentIndex, count -> getEntry←-
Batch(currentIndex, count)}
• Generic: an Object that results in any of the above on runtime
The setting is used for generic reusable tlns:soapServer="lsps/types/soapServerables when the user
wants to fill the same table with different data queried in different ways.
3. If you are using the Data data kind, define the Data count property, the total amount of entries to be loaded.
4. Insert Grid Column components (
) into the Grid.
5. Define the properties of every Grid Column.
2.7.4.3.3.2
Setting Height of Grid
By default, the Grid defines a fixed minimum height. You can change the height using the height-by-rows presentation hint. If the grid displays more rows than its minimum height, the grid becomes scrollable.
Figure 2.103 Grid with a scroll
2.7.4.3.3.3
Defining a Grid Column
A Grid Column is the child component of the Grid which displays the data of the data set object: The column defines
the Value Provider property that returns the content of the cell based on the object of the row and the Renderer that
defines how the Value Provider value is rendered.
For Grid Columns, define the following properties:
• Content: content of the Column Content can be of the following types:
– Property path: path to the Property of the row object (applicable if the Data Kind property is set to
Type)
142
Modeling
– Closure: closure with the row object as its input parameter
– Custom: custom expression
• Renderer: the way the value returned by the Value Provider is rendered in the cell
– None: renders the Value Provider value as is
– HTML: renders the Value Provider value as HTML
– Number: renders the Value Provider value in the defined format Define the format as a String following
the DecimalFormat Java formatting rules, for example, "0000.00000"
– Date: renders the Value Provider value in the defined format Define the format as a String following the
SimpleDateFormat Java formatting rules, for example, "EEE, d MMM yyyy HH←:mm:ss" will result in formatting like Wed, 7 Sep 2016 14:33:00
– Button: renders the Value Provider value as a Button The action that should be performed on click is
defined as a closure with the Value Provider object as its input parameter.
1 { clickRowObject:String -> varString := "The user clicked: " + clickRowObject.toString();
MyEditableGrid.refresh()}
– Link: renders the Value Provider value as a Link The action that should be performed on click is defined
as a closure with the Value Provider object as its input parameter.
1 { clickRowObject:String -> varString := "The user clicked: " + clickRowObject.toString();
MyEditableGrid.refresh()}
– Theme image: image from your Vaadin ThemeResource
To be able to use this option, the Value Provider must return a String with the path to the image. The path is relative to current Vaadin theme directory, for example, myapp-war/VAADI←N/themes/lsps-blue, so the String path could be "favicon.png".
– External image: image
To be able to use this option, the Value Provider must return a String with the URL to the image. For
example, External image renderer could be used if for a Closure Value Provider set to {a:Applicant
-> "www.acme.com/images/" + a.pictureName}.
– Custom: custom implementation of the ui::Renderer interface
2.7.4.3.3.4
Handling Action on Renderers
In a Grid, you can handle clicks on Grid Columns with Button, Link, Theme image, and External image renderers:
1. Define the Grid Column with one of the Renderer types.
2. Select the Renderer in the Form to display its properties in the Properties view.
3. In the Properties view, click the Event Handling tab and click Add.
4. Define the listener type to RendererClickListener.
2.7 Forms
2.7.4.3.3.5
143
Freezing Grid Columns for Horizontal Scroll
To freeze one or multiple columns of a Grid, so they remain displayed when the user uses horizontal scroll, set the
Freeze column count property on the Grid to the number of columns to remain displayed.
144
Modeling
2.7.4.3.3.6
Enabling Editing of a Grid Column
You can make cells of a Grid Column editable in the following case:
• The parent Grid has the Data Kind property set to Type.
• The Grid Column with the value has the Value Provider set to Property Path; otherwise the cell value will not
be editable and that even if the Grid is editable.
Important: If the underlying associated shared Record Property returns null, the cell will remain
empty and uneditable.
To enable editing of shared Record Properties in a Grid, do the following:
1. Open the Properties view of the Grid:
(a) Select the Editor enabled flag.
(b) To save the changes only when the user clicks the Save button in the edited row, select the Editor
buffered flag.
If the Editor buffered is not selected, the changes are applied to the underlying Record instantly (on
every change).
2. Enable editing on the Grid Column:
(a) Open the properties of your Grid Column.
(b) Select the Editable flag.
(c) In the Editor field, define which editor should be used on the Value Provider object:
• leave empty for Strings
• NumberEditor: the user will be able only to provide a number (Decimal or Integer)
• DateEditor: the user will be able to insert only a date with the option to use a date picker
• EnumerationEditor: the user will be able to select one of the Enumeration value from a drop-down
box
2.7 Forms
145
Figure 2.104 Definition of a Grid Column with an editable number value
Figure 2.105 Editable Column with a validation message on incorrect value
2.7.4.3.3.7
Filtering and Sorting on a Grid Column
To enable filtering or sorting on a Column of your Grid, open the Properties view of the Column and check the
Sorting or Filtering flag.
146
Modeling
2.7.4.3.4
Repeater
The Repeater component is a Form output component that renders its child component multiple times.
• Data: list of objects to iterate through
• Data iterator: reference to the iterated object (Since an iterator holds the value of the object for the current
iteration, the referenced object must be of the same type as the Data list objects)
Important: If you define a reference to a variable as iterator, make sure the variable is used solely
as the repeater iterator.
• Layout: a RepeaterLayout that defines the layout applied on child elements
– RepeaterLayout.wrap: repeated items are arranged horizontally; if their content is larger than the
width wrapping, the lines overflow.
– RepeaterLayout.horizontal: repeated items are arranged horizontally. Their size is ignored.
– RepeaterLayout.vertical: repeated items are arranged vertically. Their size is ignored. If
some of the child elements are not displayed in the repeater, set the child components width to Wrap
Content.
Important: The Layout property is not recalculated on refresh.
• Index iterator: reference to an Integer variable that holds the index of the currently iterated object
2.7 Forms
2.7.4.3.5
147
Image
The Image component is a Form output component that renders an image File object.
Note: The File object cannot be created directly over a file in the file system. Therefore, you need to
import the image into your project (File Import General File System) and create the File object over the
imported image.
• Content: the image object to be displayed
• Text: image caption
• Help text: tooltip text
Note: You can define the Help text on the Help Text tab in the Properties view.
2.7.4.3.6
Navigation Link
The Navigation Link component renders as a hyperlink that redirect the user to navigation target.
• Content: the Navigation object to be used for navigation
1 new UrlNavigation(url -> "http://www.whitestein.com")
• Text: text displayed in the navigation link
• Disabled: whether the link is disabled (rendered as grayed out and not clickable)
• Help text: tooltip text
Note: You can define the Help text on the Help Text tab in the Properties view.
148
Modeling
2.7.4.3.7
File Download
The File Download component allows the user to download a file and renders as a hyperlink.
It produces events of the following types:
• InitEvent when the component is initialized or displayed if previously hidden
• ∗FileDownloadEvent∗∗ when the user clicks the file-download button
• Content: File object with the file
• Text: text of the download hyperlink
• Help text: tooltip text
2.7.4.3.8
Pie Chart
The Pie Chart is a circular chart that depicts data values as sections.
It produces events of the following types:
• InitEvent when the component is initialized or displayed if previously hidden
• ChartClickEvent when the user clicks a chart
The event contains data about the clicked data series and its data point along with the data point payload.
Figure 2.106 Pie chart with legend
The Pie Chart component has the following properties:
2.7 Forms
149
• Title: pie chart main title
• Subtitle: pie chart subtitle
• Slices: pie chart sections List of slices displayed in the pie chart. The slices define their label and value.
Slice value is defined as decimal value and represents the mutual ratio of individual slices.
1 collect(getCurrentAssets(), {asset -> new ui::PieSlice(label -> asset.ISIN, value -> asset.currentAmount)})
• Show legend: visibility of the chart legend (if true, the legend is visible)
2.7.4.3.9
Gauge Chart
The Gauge Chart is a chart with one chart with a circular Y-axis with a rotating pointer.
It produces events of the following types:
• InitEvent when the component is initialized or displayed if previously hidden
• ChartClickEvent when the user clicks a chart
The event contains data about the clicked data series and its data point along with the data point payload.
Figure 2.107 Form with the Asset gauge chart displaying asset price
Gauge Chart Properties
150
Modeling
• Title: gauge chart main title
• Subtitle: gauge chart subtitle
• Value: value displayed by the pointer (needle)
• Value name: value name displayed in the pointer tooltip along with the Value
• Axis: gauge axis that defines the gauge chart scale, label, properties of the scale, bands, and chart position:
The gauge axis constructor takes the following arguments:
– min and max: minimal and maximal values on the gauge scale
– label: label displayed directly on the gauge chart
– opposite: position of the axis (if true, the axis is displayed on the edge of the gauge circle; if false, the
axis is displayed inside the gauge circle)
– bands: plot bands (shown white, blue, and red in the gauge chart figure above; CCS color definitions
are supported)
– startAngle and endAngle: start and end angle of the gauge axis
– centerY: horizontal positioning of the gauge chart middle in percent (“50” places the chart directly under
its title with no gap in between)
Example Axis definition
1 new
2
3
4
5
6
7
8
9
10
11
12
ui::GaugeAxis(
min -> 0,
max -> 80,
label -> "axis label",
opposite -> null,
bands -> [
new PlotBand(from -> 0, to -> 20, color -> "#FFFFFF"),
new PlotBand(from -> 20, to -> 40, color -> "blue"),
new PlotBand(from -> 40, to -> 50, color -> "red")],
startAngle -> 300,
endAngle -> 420,
centerY -> 120)
Figure 2.108 Rendered gauge chart with the axis as defined above
• Show legend: visibility of the chart legend This property is not applicable for the gauge chart component.
2.7 Forms
2.7.4.3.10
151
Cartesian and Polar Chart
The Cartesian Chart is a multi-dimensional chart with an arbitrary number of x and y axes. The rendering of the x
axis depends on the given data series, while the y axis displays the value connected to the x value defined as a
data point.
The Polar Chart is a variation of the Cartesian chart. It is rendered as a circle whose circumference is the x axis
and its radius is the y axis. Just like the Cartesian chart, it is multi-dimensional chart, that is, it can have n arbitrary
number of x and y axes. However, though this option is functional, the y axes are overlaid over each other in a single
radius.
It produces events of the following types:
• InitEvent when the component is initialized or displayed if previously hidden
• ChartClickEvent when the user clicks a chart
The event contains data about the clicked data series and its data point along with the data point payload.
Note that the chart-click event holds data about the clicked data point and the listener can use this data, for example,
to drill down into the chart or visualize details related to the data point.
Cartesian and Polar Chart Properties
• Title: chart main title
• Subtitle: chart subtitle
• Series: a set of data series displayed in the chart (see data series)
• X axes: list of x chart axes
You can define multiple x axes. The axes are arranged underneath or next to each other depending on their
orientation.
• Y axes: list of y chart axes You can define multiple y axes. The axes are arranged underneath or next to each
other depending on their orientation.
Axes for Cartesian and Polar chart define the following properties:
– min and max: minimal and maximal values on the axis
– label: label displayed directly on the chart
– opposite: position of the axis (if true, the axis is displayed as the opposite axis, that is x is displayed as
y and vice versa
– bands: plot bands (any CCS colors are supported)
• Rotate axes: Boolean value that defines whether the x and y axes are rotated (for example, if true, chart bars
can be displayed horizontally) This option is not available for the Polar Chart component.
• Show legend: visibility of the chart legend (if true, the legend is visible)
Data series defines a set of data points that are displayed as values in the chart. It also defines general properties
of the data series:
• label: the data series label in the legend and tooltip of the plotted data series
• options: plotting options
• xAxisIndex: index of the x axis the data series uses
152
Modeling
• yAxisIndex: index of the y axis the data series uses
Since chart axes are defined as lists, the xAxisIndex and yAxisIndex are defined as integers with the first
defined axis being indexed 0.
Important: The ui::DataSeries record is abstract: Define the Data Series as one of its sub-types.
One chart can display multiple data series of different types. The type of a data series defines the way its x axis
renders (note that a chart may contain multiple x or y axes):
• ListDataSeries: the x axis values are integers.
Values are defined as a list of data points (List<DataPoint>) and are distributed evenly as depicted below.
Figure 2.109 Cartesian chart with ListDataSeries (“Company A” and “Index”) and the series definition
(further below)
@image html listDSDefinition.png " Cartesian chart with ListDataSeries (“Company A” and “Index”) and the
2.7 Forms
153
Figure 2.110 Cartesian chart with ListDataSeries (“Company A” and “Index”) and the series definition
(further below)
• CategoryDataSeries: the x axis values are arbitrary string values.
Values are defined as a map of Strings and DataPoints (Map<String, DataPoint>): the String is used as
the value on the x axis and the data point defines the values on the y axis.
154
Modeling
Figure 2.111 Cartesian and Polar charts with CategoryDataSeries (“World rice production” and “China rice
production”) and years as String values; The definition of the “World rice production” CategoryDataSeries
(further below)
@image html polarCategoryArea.png " Cartesian and Polar charts with CategoryDataSeries (“World rice produ
2.7 Forms
155
Figure 2.112 Cartesian and Polar charts with CategoryDataSeries (“World rice production” and “China rice
production”) and years as String values; the definition of the “World rice production” CategoryDataSeries
(further below)
@image html categoryDSDefinition.png " Cartesian and Polar charts with CategoryDataSeries (“World rice pr
156
Modeling
Figure 2.113 Cartesian and Polar charts with CategoryDataSeries (“World rice production” and “China rice
production”) and years as String values; the definition of the “World rice production” CategoryDataSeries
(further below)
• TimedDataSeries: the x axis values are points in time.
Values are defined as a map of Dates and DataPoints(Map<Date, DataPoint>): the date is used as the
value on the x axis and the data point defines the values on the y axis.
2.7 Forms
157
Figure 2.114 Cartesian chart with TimedDataSeries (“Train delay”); the definition of the “Train delay”
TimedDataSeries (further below)
@image html cartesianTimedScatterDef.png " Cartesian chart with TimedDataSeries (“Train delay”); the defi
Figure 2.115 Cartesian chart with TimedDataSeries (“Train delay”); the definition of the “Train delay”
TimedDataSeries (further below)
• DecimalDataSeries: the x axis values are decimal numbers.
158
Modeling
Values are defined as a map of Decimals and DataPoints (Map<Decimal, DataPoint>): the decimal is used
as the value on the x axis and the data point defines the values on the y axis.
2.7.4.3.10.1
Plotting Options
Plotting options define how a set of data renders. They are defined in the options property of every data series
so that every data series in a chart can be plotted differently. If undefined, the default plotting properties for the
given data series are applied.
The following plotting options are available:
• PlotOptionsArea: the data series is rendered as an area.
• PlotOptionsBar: the data series is rendered as a set of bars.
• PlotOptionsBubble: the data series is rendered as a bubble.
Note: This plotting option is currently not supported.
• PlotOptionsScatter: the data series is rendered as a set of dots (scatter).
• PlotOptionsLine: the data series is rendered as a line.
Figure 2.116 TimedDataSeries with a PlotOptionsLine definition
2.7 Forms
2.7.4.3.11
159
Browser Frame
The Browser Frame renders as a view to a URL. To adjust the size of the frame, use presentation hints (refer to the
Standard Library).
Figure 2.117 Browser Frame to external page in a tab component
• URL: URL to be displayed in the frame
2.7.4.3.12
Calendar
) component is rendered as a calendar with calendar entries. The calendar entries are clickable
The Calendar (
and can be dragged-and-dropped. You can also select the calendar mode in the calendar. These actions fire the
respective events.
It produces events of the following types:
• InitEvent when the component is initialized or displayed if previously hidden
• CalendarEditEvent when the user clicks a calendar entry
• CalendarRescheduleEvent when the user drags a calendar entry
• CalendarCreateEvent when the user selects a time period by clicking and dragging
160
Modeling
The calendar component is displayed in month mode by default. To display a day schedule, click the day date in the
calendar cell. Note that if a calendar entry needs to be scheduled in the day mode and keep track of exact hours,
the allDay property of the entry must be set to false.
• Data: closure that returns a set of business data for the calendar (the data contains information about individual calendar entries)
1 {
2
3
4
5
6
7
8
9
10 }
x, y -> def Set<Object> result:={};
foreach Note n in notes do
if n.notetype == NoteType.MEETING
then
result:=add(result, n)
end;
end;
result
• To item: closure that transforms the data from the set defined in the Data property to CalendarItem
1 { mynote:Note -> new ui::CalendarItem(
2
caption -> mynote.description,
3
description -> "Imported MEETING note",
4
from -> mynote.time.from,
5
to -> mynote.time.to,
6
allDay -> true ,
7
style -> null)}
• Initial Date: date that is selected in the calendar when first opened (By default, the current date is selected.)
• Mode: calendar display mode
The property determines the way a calendar is display initially and after refresh. The possible values are
daily, weekly, monthly.
• Read only: calendar renders as read-only and cannot be edited
If read-only, CalendarRescheduleEvent, CalendarCreateEvent are not fired. CalendarEditEvent is fired to
allow the form to display an event details.
2.7.4.3.13
Map Display
The Map Display component renders as an OpenStreetMap with the defined center location, zoom, and optionally
also markers. You can drag the map to change the visualized area and zoom it in and out. The map markers can
be draggable.
It produces events of the following types:
• InitEvent when the component is initialized or displayed if previously hidden
• MapClickedEvent when the user clicks the map (The event holds the clicked coordinates.)
• MarkerClickEvent when the user click a map marker (The event holds the data on the marker.)
• MarkerDraggedEvent when the user drags a marker (The event holds the data on the marker, and its original
and new position.)
Map Properties
• Center: coordinates of the center of the rendered map
• Zoom: default zoom on initialization and refresh defined as an integer with value 0-18 (0 being the lowest
zoom with the entire Earth displayed)
2.7 Forms
161
• Markers: set of business data that are used as map markers
1 { [new Meeting(
2
title -> "Whitestein Meeting",
3
location -> whitesteinHeadquarters,
4
can_reschedule -> false,
5
attendees -> ["Vladimir", Estragon]
6
] }
• To marker: expression that converts the business data from Markers to MapMarker objects
1 { x:Meeting -> new ui::MapMarker
2 (
3
title -> x.title,
4
location -> x.location,
5
popup -> x.title + "<BR/>Atendees: " + x.attendees,
6
draggable -> x.can_reschedule
7
)
8 }
2.7.4.4
Action Components
Action components produce an action event when clicked.
2.7.4.4.1
Action Button
The Action Button component renders as a button. On click the button produces an action event. The component
can have an ActionListener that defines how the event should be handled.
It produces the events of the following types:
• InitEvent when the component is initialized or displayed if previously hidden
• ActionEvent when the user clicks the component
Figure 2.118 Tab with the Submit note Action Button
• Text: text on the button
• Disabled: availability of the button
If true, the button is grayed out and cannot be clicked.
• Help text: tooltip text
Note: You can define the Help text on the Help Text tab in the Properties view.
162
Modeling
2.7.4.4.2
Action Link
The Action Link component renders as a clickable link. On clicking the link produces an action event. The component can have an ActionListener that defines how the event should be handled. The handling typically involves
navigation action.
It produces the events of the following types:
• InitEvent when the component is initialized or displayed if previously hidden
• ActionEvent when the user clicks the component
Figure 2.119 Tab with the Link to note Action Link
• Text: link text
• Disabled: whether the link is disabled (rendered as grayed out and not clickable)
• Help text: tooltip text
Note: You can define the Help text on the Help Text tab in the Properties view.
2.7.4.5
Special Components
2.7.4.5.1
Message
The Message component displays validation messages of failed validators in the chosen Form location. It is useful
if you do not want to display these in the components with failed validation.
2.7.4.5.2
Expression
The Expression component defines an expression that returns a component.
Important: The expression is evaluated when the screen context and cannot be recalculated later.
2.7.4.5.3
Reusable Form
Reusable Form component references a form: on runtime, the form is inserted into the tree of components and
becomes a part of the form tree. The form is called and resolved when the screen context is created.
Note that if you want to work with events of such injected reused form in other form components or process events
from other nodes inside the reused form, you will need to explicitly allow such event distribution.
2.7 Forms
2.7.4.5.4
163
Conditional
The Conditional component is a form component that defines the visibility of its child components: if the Visibility
property evaluates to false and the parent component is visualized or refreshed then the child components are
not displayed; the children do not exist at all. Therefore it is not possible to operate over the child components
unless the Conditional component defines them as visible.
Properties:
• isModal: modality of the popup (if true when the popup is displayed, you cannot work with the underlying
form)
2.7.4.5.5
View Model
The View Model component serves to isolate changes on a set of data so that the changes can be applied at once
or thrown away without compromising the underlying data later.
A View Model creates a context on an evaluation context level which overlays the current level:
• if you insert a view model into a form and it has no other view model as its parent, the view model creates a
context on the first evaluation level.
• if you insert a view model into a form and it has a view model as one of its parent elements, the view model
creates a context on the evaluation level overlaying the evaluation level of the parent view model.
The content of the view model exists in its own execution context on an evaluation level. When the user changes the
data in components of a view model, they are changing them on another execution level that the screen level. You
can define when the changes are applied to the contexts in the underlying levels or discarded. The level to which
the changes are applied is defined by the merge type of the view model:
• MergeType.oneLevel: the view model context is merged into the immediate underlying level
• MergeType.screenLevel: the view model context is merged into the screen level
Merge or cancel action is defined on listeners.
For a view model use case, refer to Pop-up with Apply and Cancel Buttons.
2.7.4.5.5.1
Isolating Transient Data Using View Model
To isolate transient component data use the View Model component: The component provides a "commit mechanism" by creating a context on another evaluation level. A context on an evaluation level overlays the original
context so the components inside the View Model work with data in their own space. You can use a view model, for
example, to implement a cancel action when editing data: the user will edit the data in the View Model and the view
model will be discarded or merged on a button click.
Generally you will proceed as follows:
1. Insert the View Model component into your Form. Make sure to define its name and merge type.
2. Into the View Model, insert Input Form components that will allow the user to modify the data.
3. In the View Model, create components with listeners that will merge or clear the data from your View Model:
On the listener's Advanced tab:
164
Modeling
• To apply the data changes from a View Model, enter the View Model name to the Merge view model
components property.
• To discard the data change from a View Model, enter the View Model name to the Clear view model
components.
You might want to define the View model init expression on the listeners: the expression is executed right after the
merge or clear of view models.
Alternatively, you can call the merge() and clear() functions from the handle expression.
See Pop-up with Apply and Cancel Buttons for example usage.
For example, let us assume the form below.
Figure 2.120 Form with multiple view models
Note the following:
• View Model B has the Merge type property set to MergeType.screenLevel
• The "Value of Variable A" TextBox is bound to variable A and has the Immediate property set to true.
• The ValueChangeListener refreshes the entire form and merges the View Model B (set in the listener properties).
On runtime, if you change the variable A value in the text box, the value will be merged to the screen context via
the underlying evaluation level: hence also the context in of View Model A will have the change reflected and the
displayed value will be updated.
For a view model use case, refer to Pop-up with Apply and Cancel Buttons.
2.7 Forms
2.7.4.5.6
165
Geolocator
The Geolocator component serves to acquire user's location. The location is detected on initialization and every
component refresh. Note the component is not rendered in a form and is intended to provide input data for other
components such as the map component.
The location is acquired either from the Wi-Fi or BTS location with accuracy from 300 to 3.000 meters, or from GPS
with accuracy from 1 to 10 meters.
Note: When a form with a Geolocator component is rendered, the browser asks the user whether he
wants to enable the locating.
It produces events of the following types:
• InitEvent when the component is initialized or displayed if previously hidden
• Geolocation event when the Geolocator component acquires user's location
Note that as of the time of writing, Firefox version 24 and later do not support geolocation.
The Geolocator component has the following properties:
• Detect: enables or disables the location detection (If false the location is not detected on component
refresh; this feature allows the user to disable the location detection, for example, via an action button.)
• Position Options:
options of the location detection (for details, refer to PositionOption in ui←-
::components.datatypes)
2.7.4.5.6.1
Acquiring Location
To acquire location of the user in your form, do the following:
1. Insert a Geolocator component into your form.
2. On the Geolocator component, create the GeolocationListener.
3. To work with the received location, in the Handle expression, handle the event's position property.
166
Modeling
Figure 2.121 Handling of Geolocation event on the Geolocator component
2.7.4.6
Annotations
Annotation components display information about the form and hence have no semantic value.
2.7.4.6.1
Text Annotation
Text annotations hold description text or comments and can be connected to the related form component with a
directed or non-directed association.
2.7.4.6.2
Association
Association is a line with no semantic value that connects a text annotation with a form component, possibly another
text annotation. Alternatively, you can use a directed association, which is rendered as an arrow.
2.7.4.7
Deprecated Components
The components described in this section are deprecated and will be removed in the next release.
2.7 Forms
2.7.4.7.1
167
Tree
) component renders as a tree of nodes. The nodes are expandable unless they are leaf nodes, that
The Tree (
is, they do not have any children. Whenever a node is expanded its child nodes are lazy-loaded. To acquire the child
nodes, the Tree component calls the closure defined in the Children property. The closure returns a List<TreeItem>
objects.
The TreeItem objects define the following:
• label (String): arbitrary text displayed as the node label
• expanded (Boolean): whether the node is expanded by default
• data (Object): business object the tree item operates over
The Tree component serves as a picker of exactly one option (node). Once the user selects a node, the selection is
stored in the Binding slot.
Figure 2.122 Tree with multiple nodes expanded
The Tree component has the following properties:
• Label: visible label
• Required: compulsoriness of the tree component
If true, a mark indicating that the value is required is rendered in the component.
Important: The property does not provide any validation whether the field contains a value and
the user will be able to submit a null value unless a additional validation mechanism is defined.
Such a validation can be implemented on a listener, possibly as a validation expression.
• Binding: reference to a slot that holds the selected tree option value (for example, a form variable or global
variable)
• Children: closure that returns a list of tree items which are displayed when a node is expanded
168
Modeling
1 { parent:Position,depth:Integer -\> compact(collect(positions, {p:Position -\> p.parent=parent ? new
TreeItem (data -\>p, expanded -\>false, label -\>p.name) : null}))}
• Read-only: editability
If true, the tree renders as grayed out and no option can be selected. The selection uses the value of the
binding slot.
• Immediate: setting of immediate mode
If true, the Immediate mode is active: any value changes are processed immediately.
• Help text: tooltip text
Note: You can define the Help text on the Help Text tab in the Properties view.
2.7.4.7.2
Tree Table
The Tree Table component renders as a table with rows organized in a tree structure with rows as tree nodes.
Hence, child rows can be collapsed.
The component works similarly to the Table component. However while a table operates directly over business data
types, the tree table components wraps the business data in the TreeTableItem data type objects. The TreeTable←Item object hold the business data along with additional information. Based on the additional information, the tree
table either expands the node that represents the business data or keeps it collapsed.
The tree table component iterates through a List<TreeTableItem> object. The TreeTableItem objects content can
be then further processed (for example, displayed or provided for editing) in the table's columns.
The TreeTableItem objects define the following:
• expanded (Boolean): whether the node is expanded by default
• data (Object): business object the tree table item operates over (business data you want to work with in the
tree table)
Figure 2.123 Tree Table with multiple nodes expanded
The Tree Table component has the following properties:
2.7 Forms
169
• ID: component ID unique in the form (Only capital letters, digits, and underscores are allowed.)
• Children: closure that returns a list of tree table items that are displayed when a node is expanded
• Iterator: reference to an object of the business data type
The object is used as iterator for the table tree items.
Important:The iterator is not of the TreeTableItem type but of the type of your business data←: the List<TreeTableItem> holds TreeTableItem objects, while the TreeTableItems objects hold the
business objects in data and serve to provide the additional expanded property.
• Help text: tooltip text
Note: You can define the Help text on the Help Text tab in the Properties view.
2.7.5
Patterns
This chapter contains patterns with happy-flow examples.
2.7.5.1
Editable Table
Required result:
• Table with columns with editable values.
• One of the column contains a drop-down list with the possible options. The options are based on an enumeration.
• The table values are persisted when you click the Submit button.
To create a document or a to-do with such a table, you need to do the following:
1. Create the data type model with a shared record for the persisted entity and the enumeration.
Figure 2.124 The underlying data type hierarchy
2. Create the form definition.
170
Modeling
(a) Create a local variable of the shared record type: The table will use the variable as its iterator.
(b) In the form, add the Table component and define its properties on the Detail tab:
i. Define the reference to the local variable as the iterator on the form.
ii. Set Data Kind.
iii. Define the Data expression.
In this pattern, we assume you are using the Data Kind set to Data with the Data expression defined as
a closure with 2 input parameters:{x, y -> getAllApplicants()}
(c) In the table component, insert the Column components.
(d) In the columns, add the Input components.
Figure 2.125 Asset table with columns with two text boxes and one combo box
In the example, we inserted two Text Boxes and one Combo Box:
i. On Text Boxes, define the binding to the reference to the iterator fields, for example, &i.level.
ii. On the Combo Box component, define the options to be displayed in the drop-down area.
To bind options to the enumeration, convert the enumeration literals to options. You can do so using the
collect() and literalToName() functions.
1 collect(literals(type(AssetType)),
2
{e -> new ui::Option(value -> e,
3
label -> literalToName(e))})
(e) Define the Submit button:
i. Insert the Button component into the form.
ii. Create ActionListener on it.
iii. On the listener properties, select the Submit action on the Actions tab.
iv. Optionally, set the text that should be displayed in the table if it contains no entries: on the Presentation Hint tab of the table properties, add the no-data-mesage hint.
3. Create a document or a process with a to-do that uses the form.
2.7.5.2
Sortable Table
Required result:
A table with Data Kind set to Data has sortable columns: when the user clicks a column header, the table is sorted
according to the column values.
Crucial for a sortable table is the sorting mechanism: in this example, we will use ordering defined on a non-native
query. The query will define a dynamic ordering expression with an ordering enumeration. A list of enumerations
will be the parameter of the query. The parameter will be resolved by the table.
2.7 Forms
171
The table columns will define the ordering enumeration that applies to the column's content. These values will be
stored in the storeVar variable.
The table will orchestrate the content of the variable, depending on the user clicks. The content of the variable will
be sent a parameter to the query and used in the sorting of the query.
You need to do the following:
• Create the data type model with the shared record. In this example, we use a shared record Book with the
Title and Author fields, both of type String.
Figure 2.126 Data model
• Create a query that will take a sort parameter. The sort parameter will define how to sort the returned objects.
• Create a form with a table that acquires its data using the query with the sort parameter and two columns that
set the ordering parameter.
2.7.5.2.1
Query
To define the query for the table, do the following:
1. Create the query with the following properties:
• Record type: Set the return type to the shared record Book
• Iterator: Define the iterator as b
• Ordering enumeration name: BookOrder with values of the relevant iterator fields
The Ordering Enumeration Name and Its Possible Values
Figure 2.127 Ordering enumeration definition
172
Modeling
• Parameters: sort of the List<BookOrder> type
This parameter will be sent by the table. Note that the parameter is of the ordering enumeration type
and hence can take only the values defined above.
• Ordering expression:
1 //The ordering expression sets the ordering to ‘[BookOrder.titleAcs]‘ if no the sort parameter is null or
an empty List. Otherwise the ordering expression takes the value of the sort parameter:
2 if (sort=null or sort=[]) then
3 [BookOrder.titleAsc]
4 else sort
5 end
• Condition: true (we want the query to return all entities)
2.7.5.2.2
Form
To create a form with the sortable table, do the following:
1. Create a form definition with the book <Book> variable that will be used as the table iterator and the sortVar
List<BookOrder> that will hold the ordering expression.
2. In the form, create a table component with two columns.
3. On the table, set the following properties:
• Set the iterator to &book.
• Set the Sort property to &sortVar.
• In the Data property define a closure that will return the query call with sortVar as its parameter.
1 { x, y -> if size(sortVar)>2
2
then sortVar:=removeAt(sortVar, 2)
3 end;
4 getBooks(sortVar)}
4. On the table columns, define the Sort asc and Sort desc to the respective ordering enumeration values.
5. Add the column components (for example, output text).
6. Run the Form Preview to see the resulting form.
7. Create a document or a process with a to-do that uses the form.
2.7 Forms
173
Figure 2.128 Resulting Sortable Table with Dummy Data
2.7.5.3
Table with Derived Values
Required result:
A table with columns with editable values.
Values in one column are values of a record field while another column contains values derived from the value in
the previous column. The values depend on each other and change accordingly when the respective connected
value is changed.
We need to:
• Create the underlying data type hierarchy:
– Create the base record, which is a shared record.
– Create a non-shared record with fields for the derived values.
– Associate the derived record with the base record.
Also, you need to create a form variable of a collection type with the derived record objects, for example,
(List<DerivedRecord>. It will hold all the items of the derived type (in the example below, the variable is initialized with the collect() function invoked on the objects of the shared base record. The variable hence contains all the
data to be displayed in the table from the very beginning).
Note that you cannot use the supertyping mechanism since a shared record is involved:
• If you had a derived non-shared record that is the supertype of the base shared record, the derived record
would include the fields of the base shared record but the shared record itself could not be recovered efficiently.
174
Modeling
• If you decided to define the base shared record as the supertype of the wrapper non-shared record, whenever
you decide to refresh the table with the record data, new shared record instances would be created and written
in the database.
To create a document or a to-do with the form described above, do the following:
1. Create the data type model:
(a) Create or import the base record.
(b) Create a record with the derived field.
(c) Define an association between the records: the derived record is the target of the relationship.
Figure 2.129 Base shared record TimeDeposit associated with the derived non-shared record Withdrawal
2. Create the form definition.
(a) Create a local variable of the collection type with the derived records (for example, List<Withdrawal>).
The table will use the variable to acquire its data (the Data property of the table).
2.7 Forms
175
Figure 2.130 The form variable with the initial values to be displayed by the table
(a) Define a local variable of the derived record type. The variable will serve as the iteration variable for the
table.
(b) In the form, add the Table component: Define the variable created in step b as its iterator and define the
variable created in step a as the closure return value in the Data property.
Figure 2.131 Form structure with the table properties below
176
Modeling
(c) In the table component, insert Column components and input components as their child components:
define the binding of the input components to the respective field of the iteration variable (in the example,
&currentWithdrawal.timedeposit.interestRate and &currentWithdrawal.←withdrawalDate).
3. On both input components define the following:
(a) Create ValueChangeListeners: as the component to refresh define the other input component and as
Handle expression, define the new value of the iterator field, for example, using a function. Do not define
the column as the component to be refreshed. Columns do not support the refresh action.
1 currentWithdrawal.withdrawalDate:= countWithdrawalDate(currentWithdrawal.timedeposit.interest)
(b) Set the Immediate property to true. With this Immediate setting, the value changes are processed
always when the user clicks out of the input component or hits enter.
4. Create a document or a process with a to-do that uses the form.
2.7.5.4
Calendar with Adding Entries Functionality
Required result:
Form with a calendar into which you can add entries: entries are added after selecting dates in the calendar in a
pop-up dialog.
The added entries will be instantly stored in the underlying database hence will operate over shared records.
To create such a form you need to do the following:
1. Create or import the shared record that will present your calendar entries.
Figure 2.132 Shared record for calendar entries derived from the CalendarItem record
2.7 Forms
177
2. Create a form definition.
3. In the form, create a form variable of the calendar entry type.
The variable will hold the data about the new calendar entry. For the example above, the variable will be of
the CustomCalendarItem type.
4. Open the form in the form editor, and insert a vertical layout component and a calendar component into the
vertical layout.
Figure 2.133 Vertical layout with calendar component
5. Define the properties of the calendar:
• Data: closure that returns all calendar entries (The closure is called on calendar initialization and
refresh: After you add a new calendar entry to the database, the calendar needs to be refreshed so
as to load and render the new calendar entry.)
1 { a, b -> (toSet(findAll(type(CustomCalendarItem)))) }
• To item: transformation of your data for your calendar entry to CalendarItem (the Calendar component
operates over CalendarItem objects).
1 { calItem:CustomCalendarItem -> new CalendarItem(caption -> calItem.caption, description ->
calItem.description, from -> calItem.from, to -> calItem.to, allDay -> calItem.allDay, style -> calItem.styl
6. Define a Boolean variable that will hold the pop-up visibility and set its initial value to false.
7. In the form, insert a view model component into the vertical layout and into it the pop-up component. Define
the view model ID and the following pop-up properties define its properties:
• ID: although component ID is not required, you will need it when displaying the pop-up (on button click,
the visibility variable will be set to true the pop-up component will be refreshed so as to have it rendered).
• Visible: variable that holds the visibility value
The view model component isolates the data in the pop-up component from the data in the form context: it
creates an evaluation context over the screen context: you will initialize the calendar entry variable when the
pop-up is displayed so as to get dates the user selects in the calendar into the pop-up. If the pop-up would not
be nested in a view model component, it would operate in the directly in the base context and the initialization
of the variable would create a shared record that would be written to the database with incomplete data.
However, if nested in the view model, the data is written only after it is submitted or persisted.
8. In the popup component, insert the vertical layout component and input components that will display the
available data (such as dates selected on the calendar) and allow the user to provide the other details for
the new calendar entry. Make sure the input components are bound to the correct fields of the Custom←CalendarItem variable.
178
Modeling
Figure 2.134 Calendar form
9. On the calendar component, create a CalendarCreateListener. The listener will listen for a click in the calendar
and provide you the event information, in this case the clicked dates. Define the following for the listener:
• On the Basic tab, enter the pop-up ID as the Refresh components value.
• On the Basic tab, define the handle expression so it sets the variable with the pop-up visibility to true (for
example, popup_visibility:=true; this setting makes sure the pop-up is visualized on refresh).
• On the Basic tab, define the handle expression so the calendar entry is initialized with the clicked dates.
The dates are provided by the event the listener is handling.
1 calEntry:=new CustomCalendarItem(caption -> null,
2
description -> null,
3
from -> _event.from,
4
to -> _event.to,
5
allDay -> null,
6
style -> null,
7
notes -> null)
10. Define the submit button in the pop-up that will persist the provided data and close the pop-up:
• In the pop-up component of the form, insert the button component and define its properties.
• Create the ActionListener on the button: make sure its handle expression hides the pop-up and that its
refresh components contain the entire form or any of the pop-ups parent components to make sure the
pop-up closes properly. Also make sure to set the view model in the Merge view model components
property to have the changes from the view model applied.
2.7 Forms
179
Figure 2.135 Listener on the submit button
2.7.5.5
Pop-up with Apply and Cancel Buttons
Required result:
A window pops up when you click a button in your form. The pop-up contains an Apply and a Cancel button. When
you click the Apply button, the data in the pop-up is applied to the data in the form and the pop-up closes. When
you click Cancel, the data in the pop-up is discarded and the pop-up closes.
To create a pop-up window with an Apply and Cancel button, do the following:
1. In your form with the data you want to edit, insert the View Model component and define its ID.
The view model will allow us to discard the data in it when the user clicks Cancel.
2. Typically, when creating new data, such as, a new Record, you will insert the component that will initialize the
variable with the input data into the View Model.
3. Create a local form variable that will hold your new data and initialize it to null.
4. Insert a Layout component into the view model.
5. Create a Boolean local variable that will govern the visibility of your popup and set its initial value to false.
6. Insert the Popup component into the Layout component and set its visibility to point to the Boolean
variable.
If your popup contains a complex Form or data, consider using the dynamic popup to prevent performance
issues: with dynamic popup the form is calculated and populated only when the popup is created, unlike the
modeled popup which is part of the form hierarchy since the hierarchy is created.
7. Insert the component that should open the pop-up into the View Model (typically a Button).
180
Modeling
8. On the component listener (ActionListener on Button):
• Initialize the variable with your data: the variable will exist in the view model context on the first evaluation
level.
• Set variable referenced by the Visible property to true.
• Set the View Model to be refreshed.
Figure 2.136 Setting Popup visibility for the ∗Apply∗ button click
9. Insert a layout component and input components into the Popup component and define their properties:
typically you will bind input components to the local variables with new data.
10. In the Popup component, insert the Action buttons that will handle the apply and cancel of the data provided
in the popup components.
11. On the Apply button, define an ActionListener with the following:
(a) In the Refresh components property, insert the ID of the root form component or a list of the respective
components (at least the view model).
(b) Handle expression that sets the window visibility to false so that the window disappears when the user
clicks the button.
(c) On the Advanced tab in the Merge view model components property, the name of your view model:
this will make sure that the data from the view model is applied on the underlying form data (the data in
the context on the screen level).
12. On the Cancel button, define an Action Listener with the following:
(a) Handle expression that sets the popup visibility to false so that the window disappears when the button
is clicked.
(b) Refresh components, including the Popup window to make sure it is hidden on cancel click.
2.7 Forms
181
(c) On the Advanced tab in the Clear view model components property, enter the name of your view model
to discard.
Figure 2.137 Setting cancel as View Model action for the ∗Cancel∗ button click
182
Modeling
Figure 2.138 Form with a popup in a view model component
2.7.5.6
Validating Initialized Forms
To validate initialized forms, model the forms as follows:
1. On the form, define an InitListener which fires an ApplicationEvent.
2. Define an ApplicationEventListener that listens for the ApplicationEvent.
3. On the ApplicationEventListener, define the validation expression.
2.7.6
Enabling Error Reporting on Components
To enable reporting of runtime errors so that they contain modeling IDs of involved components, run your server
with the -Dcom.whitestein.lsps.vaadin.ui.debug=true system property.
If you are running your server from PDS, go to Runtime Connection -> Runtime Connection Settings, select the
connection and click Edit
2.8 Localization
2.8
183
Localization
The LSPS Process Application supports switching of locales so that the GUI can be displayed in another language.
To display also the texts that originate from your Models in the correct language, you need to use localization
identifiers inn the underlying expressions: Localization identifiers are special functions that return the localization of
the string inn the current locale.
Localization identifiers support position text parameters so you can pass values to the localization text on runtime.
You can define a localization identifiers with the Localization Editor or in the Localization dialog directly from the
Expression Editor.
Note: In the Default Process Application, you can switch locales, on the Settings page. Note that the
default application supports the English, German, and Slovak locale and localization identifiers in other
languages will not be used unless you add a new locale to the application. For instructions on how to
add a new locale to the application, refer to the Developing a Custom Application guide.
2.8.1
Creating Localization Identifiers in the Localization Editor
To define a localization identifier with the Localization Editor, do the following:
1. From the GO-BPMN Explorer, create or open a localization definition (right-click a Module and select New >
Localization Definition).
Important: It is considered good practice to define localization definitions with all identifiers used
by the given module.
2. In the displayed Form editor, select the Default Language in the Default Language combo box.
Localization in this language will be used if the localization version requested from the application is not
available.
3. In the Localization Identifiers area in the left part of the editor, click Add.
4. In the Localization Details area on the right, enter the identifier name into the Identifier field.
The name must be unique within the Module.
5. In the Number of parameters field, enter the number of position parameters the identifier will take.
6. Select the Public check box if you want to use the identifiers in importing Modules.
7. In the Translations area, click Add and provide a translation of the string:
(a) In the Language drop-down box, select the language.
(b) In the Text area, type the translation: use the syntax %<position_number> to insert values of the
parameters.
184
Modeling
Figure 2.139 Identifier with parameter
2.8.2
Creating and Calling Localization Identifier in the Expression Editor
To define a localization identifier directly from the Expression Editor, do the following:
1. In the Expression Editor, type the name of the identifier as a String value and select it.
To create an identifier with parameters, define the entire value with concatenation, such as, "You
requested the following book " + getBookName() and select the entire expression: any
concatenation elements that are not string literals will be interpreted as position parameters.
2. Press Shift + Alt + L.
To change the shortcut, go to Window > Preferences, then General > Keys, search for Localize and set the
new shortcut in the Binding field.
3. In the Localize dialog, define the identifier details.
2.8 Localization
185
Figure 2.140 Localization dialog box with an identifier definition
Based on the data in the dialog box, the system creates a localization identifier in the selected localization
definition with the translation and substitute the string or the selected expression with a call of the identifier
into the expression.
2.8.3
Calling Localization Identifiers
To call a localization identifier from your expressions, use the syntax:
1 $<identifier>(<comma-separated_arguments>)
For example, to call the identifier deviceAdjust with one parameter, enter $deviceAdjust("#123", Sector
A). If the localization identifier is in an imported Module, add the Module name, for example, myModule←::$deviceAdjust("#123", Sector A).
2.8.4
Searching for Usages of Localization Identifiers
To search for usages of a localization identifier, right-click the definition of the localization identifier in the Localization
Editor and go to Search For -> Usages or select the identifier definition and press CTRL+ALT+G.
186
Modeling
2.8.5
Identifying Unlocalized Strings
If you are using localization identifiers and you want to make sure that everything is localized, you can set the
validation feature to detect unlocalized String. Note that you can mark a String as non-localizable with the hashtag
sign (#): such Strings are excluded from the validation check.
To have an unlocalized String detected on validation, do the following:
1. Go to Window > Preferences.
2. In the Preferences dialog, open the nodes Process Design Suite > Modeling > Validation
3. On the right pane in the Non-localized string item, select the validation severity.
4. Set the Ignore strings with no letters option as required.
2.9
Functions
LSPS comes with many useful functions in its Standard Library as well as other libraries. However, if you fail
to find the required function, you can implement your own functions: Functions can be implemented
• in the Expression Language You can create functions with their implementation in the Expression
Language from your PDS without SDK.
• as a reference to a Java method Implementation in Java requires the SDK and adjustment of
the LSPS application. Detailed instructions are available in the customization guide.
2.9.1
Calling Functions
Functions are called by their name followed by their parameters:
1 <FUNCTION_NAME>(<FUNCTION_PARAM1>, <FUNCTION_PARAM2>)
2.10
Task Types
Every Task in a BPMN Process is of a particular type: The task type determines the Task's logic. The task types
available by default are provided by the modules of the Standard Library.
However, if you require other tasks to perform activities specific to your business, you will need to develop your
own task types.
2.11
Queries
Queries serve to request data from the underlying LSPS database or an external database.
You can define two types of queries:
• standard queries query the data of shared records
• native queries query data with database statements
Both query types are defined in the query definition file.
Important: It is not possible to query system shared Records, such as, human::Person, human::←SavedDocuments, etc. Use functions of the Standard Library to acquire their values.
2.11 Queries
2.11.1
187
Standard Queries
A standard query returns shared Records from the database. The query definition works over HQL with its properties defined in the Expression Language.
A standard query defines the following properties:
• Name: name used when calling the query
• Record type: entries of the shared Record type retrieved from the database
• Single value: amount of the returned entries
If true, only the first entity is returned. If false, all entities are returned.
• Distinct: whether to return only unique entities
If enabled, identical entities result in a sole entity in the returned data.
• Public: availability of the query in Module imports.
If not public, importing Modules cannot use the query.
• Iterator: object used to refer to the currently processed entity
• Join: joins to other tables via Record relationships
• Parameter: query parameters
• Condition: Boolean expression which must be true for the entity to be included in the result (equivalent to
WHERE)
– Only the following functions with the entity iterator as its parameter define their database statement
equivalent: toLowerCase(), toUpperCase(), trim(), length(), substring(): no other
functions can be used in the query condition:
* getDayOfMonth(book.published)=5 as query condition is invalid since the getDay←OfMonth() function does not define its translation to SQL.
* toLowerCase(b.Author)="joseph heller" is a valid query condition since the to←LowerCase() function does define its translation to SQL.
– You can use the ∗ and ? wildcards. Note that it is not possible to escape these characters. If required,
consider using Native Queries instead.
Important: the condition is interpreted into SQL and the interpretation does not fully correspond to its Expression Language interpretation mainly due to the fact that the null value is
not considered a legitimate value in databases. Hence, != null is interpreted as is not
null and == null is interpreted as is null. For example, if you use the condition x
!= true as a query condition, if x is null in the database, it will not be included in the results.
• Join Todo List: allows to create a join to a list of to-dos, which are ALIVE
If the shared Record has a relationship to the human::Todo record, you can use the join to get the to-dos
related to your Record, typically, in the Condition. This mechanism makes up for the absence of the direct
access the to-do database tables. For an example on how a joined To-Do list can be used, refer to the
tutorial on extending Todo.
• Query Todo Iterator: object that holds the current To-Do
• Todo List Criteria: criteria for the to-do entries
1 new TodoListCriteria(person -> p, includeSubstituted -> true, includeAllocatedByOthers -> true)
• Paging: only the query entities starting from the Start Index position to the Start Index Result size are
returned.
If the start index and result size are both null, the query returns all results: no paging is applied. If you keep
track of the current start index, the mechanism allows paging. The following properties are required when
paging the results:
188
Modeling
• Start Index: index of the first entity returned in a result
• Result size: size of the batch request (maximum number of entities returned by the query starting from the
start index position)
• Generate count query: if checked, the system generates a function that takes the same parameters as the
query and returns the number of entities in the result set.
By default, the count function uses the name of the query with the _count suffix. To set a custom name,
enter it in the entry field next to the check box.
• Dynamic Ordering and Static Ordering and Static Ordering:
Sorting of the result set with the dynamic ordering definition evaluated on runtime and static ordering remaining unchanged.
• Fetch joins: initialize join entities with the entity's parents with a single select Fetch joins prevent performance
problems that occur when every record is fetched with a separate database select.
2.11.1.1
Filtering of Results in Standard Queries
You can filter the query results:
• depending on the values in the queried Record: define the filter condition in the condition of the query definitions
• depending on the values in the related Records: define a join in the query definition.
2.11.1.1.1
Defining a Join in Standard Queries
Joins in Queries allow you to filter the Record entries based on their related Record data, such as, get Authors who
wrote a Book in 1983, where you would use inner join to author's book and check if a book was published in 1983.
They can be defined for Records that are connected to the returned Record with a Data Relationship with a named
end. Note that joining on a query does not fetch the joined table: the query still returns only Records of the query
return type.
To define a join to your standard query, do the following:
1. Open the query definition.
2. Click Add join below the Iterator or the + button in an existing join.
3. Define the join properties:
• Iterator: name of the iterator with the related Record
• Record type: the joined Record type
• Join type:
– full: all Records that meet the conditions
The query will perform a cross join: it collects the Records and the joined Records, combines each
Record with each joined Record, and applies the query condition on the results.
– inner: the query will return only the entities, which have values in all shared records (if any shared
record entry is missing, the resulting entity is not returned)
– outer: the query will return any resulting entities with at least one missing value in any of the shared
Records
Note: Inner and outer join are always left joins.
2.11 Queries
189
• Path expression: path from the iterator Record to the Record for the join Path expression must start
with one of the iterators, either join iterators or shared Record iterators, and the name of the Data Relationship separated by the dot operator. You can use multiple names of Data Relationships separated by
the operator. It must return a single instance of its type, or a list or set of instances of such a type.
• Condition (for path expression): condition applied on the join table entities The condition is useful when
the join is an outer join, since it is checked on a smaller set of entities as opposed to being checked on
all entities when defined as the query condition. Under these circumstances, the condition can improve
performance.
2.11.1.2
Ordering in Standard Queries
To order the entities returned by a standard query, define the list of record properties used for ordering of the result
entries: the entities are then ordered according to the values of the first property; if records contain the same value
in the property, the second property is used for ordering, etc.
You can define ordering as dynamic or static:
• Dynamic ordering is based on an expression that is evaluated on runtime.
• Static ordering: the ordering is based on a list of ordering paths and every call returns the records in the same
order.
If you define both static and dynamic ordering, the static ordering takes precedence over the dynamic ordering: if
you define static ordering of book records according to their author and dynamic ordering according to their title, the
results will be ordered primarily based on their author and only on the next level ordered according to their title.
190
Modeling
2.11.1.2.1
Defining Dynamic Ordering
Dynamic ordering defines an ordering expression which returns a list of order-enumeration values. It is evaluated
for every query call so the data can be ordered differently on every call. The database query can return the records
in a different order on different calls; for example, the ordering expression can use the query parameters, where the
incoming parameter holds a list of ordering enumerations.
To define your query to return results ordered based on runtime data, do the following:
1. Create a query or open an existing query.
2. Expand Dynamic Ordering.
3. Define Ordering expression.
4. Define ordering enumeration:
(a) In the Ordering enumeration name, define the name of the ordering enumeration.
(b) In the table below, define the values of the ordering enumeration. Every enumeration value defines the
following:
• Name: name of the ordering value
• Path: path to the record field that is used for ordering The path is defined as a path to the record field
using the dot operator, that is, <ITERATOR_NAME>.<FIELD_NAME>, for example, book.←author. Every path must define its sort order as either ASC to sort the records in the ascending
order or DESC to use the descending order.
• Nulls ordering: the way the null values are ordered (default: as set in the database setting; nulls
first: null values come before any other values; nulls last: null values come after any other values)
Important: The ordering enumerations can be used by table columns to order table content. For
further details on ordering of data in tables, refer to the Process Application Forms User Guide).
5. Define the Ordering Expression.
The expression can use the incoming query parameters, where the incoming parameter holds a list of ordering
enumerations and must return a list of ordering enumerations.
Example ordering expression
1
2
3
4
//query parameter of List<Ordering_enumeration>:
queryParameter
//possible literal value:
//[OrderEnum.AssetCurASC]
Figure 2.141 Dynamic ordering in a query
2.11 Queries
2.11.1.2.2
191
Defining Static Ordering
Static ordering of queries output is based on a list of ordering paths and every call returns the records in the same
order.
To define static ordering of your query, do the following:
1. Create a query or open an existing query.
2. Expand the Static Ordering item.
3. In the Path table, define the ordering paths in the order you want to have them applied.
The ordering path must define the following:
• Path to the respective record field of the iterator in the form <ITERATOR_NAME>.<FIELD_NAME>, for
example, assetIterator.owner.email
• Sort order as either ASC to sort in the ascending order or DESC to use the descending order according to
the path field
• Nulls ordering: the way the null values are ordered (default: as set in the database setting; nulls first: null
values come before any other values; nulls last: null values come after any other values)
Figure 2.142 Static ordering query
2.11.1.3
Generating Queries for Shared Records
The mechanism for generating queries creates standard queries for shared Records of the Module.
For every shared Record, queries that return the following:
• all entries of the shared Record The queries are generated as findAll<RECORD_NAME>() queries.
• entries of the shared record with a particular ID The queries are generated as find<RECORD_NAME>By←Id(ID) queries. The ID parameter has the data type of the primary key of the shared Record.
Note, that you can re-configure the name format on generation.
To generate the definitions of such queries perform the following steps:
1. Select the module containing the shared records.
192
Modeling
2. Right-click and select Generate > Queries.
Figure 2.143 Generating queries
3. Select which queries you want to generate. To re-configure the default prefixes and suffixes of generated
queries, press the Configure button.
4. Click Finish.
2.11.2
Native Queries
A native query is a named expression that defines an SQL database query. Note that, unlike standard queries,
native queries do not rely upon shared records to query the underlying database. This allows you to make use of
native database features and possibly secure better performance.
A native query is called from an expression in the same way as a function. When called, the query requests entities
based on the defined query string. The results are stored in the defined Row type. If the query returns only the first
entity, the entity is returned as an object of the row data type. If the query returns multiple entities, they are returned
as a list of the row data type.
A native query defines the following properties:
• Name: name used to call the query
• Result type: type of the return value The type can be a primitive data type, such as a String, or a non-shared
Record.
• Single value: amount of the returned values If true only the first returned value is provided as output; if false,
all values are returned as a List of return type objects. Note that these might be subject to paging.
• Public: availability of the query in importing Modules
• Database: JNDI name of the target database (if not defined, the default database is used)
• Parameter: query parameters
Note: Parameter names must be valid identifiers unique within the query.
• Mapping: mapping of the fields of the Row type (define the mapping as a comma-separated list of the Row
type fields; note that the order of the fields defines the mapping to the returned entity values).
2.12 Data Type Model
193
• Query: expression resolved to a String that contains the SQL query
Example: Mapping and query definitions
• Mapping:
1 Currency, Price, ISIN
• Query:
1 “SELECT CURRENCY, PRICE, ASSET_ISIN FROM ASSET WHERE CURRENCY=:curr”
The CURRENCY will be mapped to Currency, PRICE to Price, and ASSET_ISIN t> o ISIN of the row type.
Note that the order of the defined fields is preserved.
2.11.3
Calling Queries
A query is called in the same way as a function: <query_name>(<parameters>).
2.12
Data Type Model
A data type model is the hierarchy of all Records–user-defined data type with an inner data-type structure–with all
their relationships in a Model.
Records resemble OOP classes:
• The structure of a Record is defined by Record Fields with every Field defining its data type, be it a built-in
data type or a Record.
• Records can inherit from each other.
• Behavior of Records is defined in methods in methods definition files.
• Records can be defined as and implement Interfaces.
In addition, Records can have Relationships between each other, which define how one Record relates or depends on another Record: Relationships allow you to establish navigation, multiplicity, and composition relationship
between two Records.
Record instances exist during the lifetime of their model instance. To persist Record instances so that they are
independent on the model instance, define the Records as shared.
Note: Further information on Records, Relationships, and related elements and mechanisms is available in GO-BPMN Modeling Language Specification. Instantiation of Records, accessing
a Record instance Fields, and related mechanism are documented in the Expression Language
guide.
To validate values of Record instances, use the provided validation mechanism.
194
2.12.1
Modeling
Creating a Data Type Model
To create a Data Type Model, do the following:
1. Open a data type definition file for editing or create one (a Module can contain multiple data type definitions):
• To create a data type definition file, right-click a Module and go to New > Data Type Definition.
• To open an existing definition file, double-click the definition in the GO-BPMN Explorer.
2. Create the Records in the definition file:
(a) Right-click into the canvas and in the context menu, select Record.
(b) Select the inserted Record:
i. Define its properties in the Properties view.
ii. Insert Fields into the Record: On the Fields tab of the Properties view, click Add.
(c) Define the Relationships and their properties if applicable: drag the quicklinker to the target Record.
(d) Define methods of Records: right-click the Record and click New Methods Definition in the context
menu: define the Record Expression Language guide.
2.12.2
Creating Records
To create a Record, do the following:
1. Open a data type definition file for editing or create one:
• To create a data type definition file, right-click a Module and go to New > Data Type Definition.
• To open an existing definition file, double-click the definition in the GO-BPMN Explorer.
2. Create the Records in the definition file:
(a) Right-click into the canvas and in the context menu, select Record.
(b) Select the inserted Record and define its basic properties on the Detail tab of the Properties view:
• Name: name unique within the Module
• Supertype: supertype Record of the Record
• Flags:
– Monitoring: displays an icon to indicate that the Record is involved in Monitoring
– Shared: shared record has its data persisted and hence is not dependent on the existence of
its model instance
– Abstract: An abstract record cannot be instantiated, but can be used as a supertype record of
another Record.
– Read-only: if true, all Fields of the Record are read-only: The Record instance is initialized on
model instantiation and can be deleted during runtime; however, neither the Record instance
nor instances of its subtype can be modified during runtime.
Read-only Records can only be targets of data relationships, but not their sources. This prevents a possible inconsistency of data.
– System: if true, the Record is read-only for the user
A model instance cannot create instances of a system Record or calculate its Field values.
Hence, the user cannot instantiate a system Record. However, it can be instantiated by a
custom tasks or functions implemented in Java, or your application code.
– Final: if true, the Record cannot be a supertype
– Deprecated: flag to denote a deprecated Record
If the attribute is true, the validation displays an information message that the Field is deprecated.
2.12 Data Type Model
195
• Label: a String that is assigned to the Record
Labels typically hold a human-readable name of a Record, Record Relationship end or Enumeration, for example, for a Record NaturalPerson, you could define the label natural
person. To display the type of a NaturalPerson record in a form, you could use the getLabel()
function, for example, myPerson.getType().getLabel(). You can use the Label also for
API calls.
Now you can insert Fields into the Record and define Relationships and their properties if applicable.
2.12.3
Creating Record Fields
To create a Record Field in a Record, do the following:
1. Select the Record or its Field and press the Insert key to add a new Field.
2. On the canvas, select the Field and define its properties in the Properties view.
• Name: name unique within the Record
• Type: data type of the record field
Either enter the type directly, for example, Set<Map<Integer, String>> or click the Define button to
use the wizard.
Figure 2.144 Defining a Record Field as a Set of Maps with Strings and Integers with the wizard
When defining a Field of a shared Record, define its database mapping attributes.
196
Modeling
It is recommended not use Fields of complex data type: If your model contains such a Field, create another
Record of the type and use Relationships to associate it with your Record.
• Label: a String that is used to represents the Record
Labels typically hold a human-readable name of a Record Field, for example, for an Enumeration literal
Weekday.MONDAY, you could define label Monday. To get the label value, for the enumeration literal,
you will use the Weekday.MONDAY.getLabel().
• Read-only: if true, the field is read-only (instantiated on model instance instantiation; not modifiable
after that)
• Deprecated: flag to denote a deprecated Record If the attribute is true, the validation displays an
information message that the Field is deprecated.
• Used for equals: if true, the field value is used as a comparison criterion. You can find further details
in Using Fields in Record Comparisons
Items displayed in the compartments indicate the visibility of the item:
• public items are marked with + and are accessible from anywhere
• protected items are marked with # and are accessible only from within the data type hierarchy (can be used
by any subtypes)
• private items are marked with - and are accessible only for the Record and its methods (define methods to
access from outside)
2.12.4
Defining Record Methods
To define methods of a Record, do the following:
1. Open or create a method definition file for the Record:
• To create a new method definition, right-click the Record and select New Methods Definition.
• To open an existing definition, double-click the methods files in the GO-BPMN Explorer.
2. Add or edit the methods following the method syntax.
2.12.5
Creating Record Subtypes
To define a Record's supertype, open its Properties view and on the Detail tab enter the name of the supertype
Record. Alternatively, select the Inheritance connector in the palette and draw the connection on the canvas.
For more information on the inheritance mechanism, refer to the GO-BPMN Modeling Language Guide.
Figure 2.145 Hierarchy of Records with multiple subtypes
2.12 Data Type Model
2.12.6
197
Creating Record Relationships
Relationships between Records establish a relationship between the Record database tables. Unlike in JPA, the
Relationship is symmetrical (set on both ends of the relationship) and hence it is not necessary to make one of
the tables the Owner. Further information on the mechanisms, related elements, comparing of records and record
properties is available in GO-BPMN Modeling Language Specification.
To create a Relationship between two Records, do the following:
1. In the Data Type Editor, click the quicklinker icon and pull the link towards the target Record.
Figure 2.146 Creating Record Relationship
2. Select the Relationship to open its Properties view: the view contains tabs with properties of the Relationship
and either relationship direction referred to as Target and Source. The assignment of ends depends on
the way you dragged the Relationship line: the Record you started is the Source end. Information on the
Relationship direction is at the top of the Properties view. Define the required properties:
• Detail tab: name of the Relationship
• Source and Target tabs:
– Name: names of the Relationship end used to navigate through to the related Record, for example,
as a Property path type Book.cover or in a Record instance myBook.cover
198
Modeling
Figure 2.147 Setting the relationship name
– Visibility: visibility of the navigation
– Multiplicity: cardinality of the relationship end
– Composition: establishes a "fixed" combination of records in the relationship
– Used for equals: when comparing instances of the records, the given relationship is included
– Label: a String that is assigned to the Record
Labels typically hold a human-readable name of the Record Relationship end; for example, for a
Record relationship end NaturalPerson.involvedInCase, you could define the label "←Pertinent case". To display the relationship end name, you could use the getLabel() function,
for example, myPerson.involvedInCase.getType().getLabel().
• Source/Target DB Mapping tabs:
– Lazy: whether loading of the related shared records is lazy or eager (refer to Fetching)
– Exclude from optimistic lock: if selected the version of the entity in the database remains unchanged when the relationship changes; hence, the entity will be changed by all commits without
collision. If not selected, and the relationship end entity is changed by multiple users at once, the
system returns a "Conflict on entity" error.
• Relationships between Shared Records define in addition the following:
– Update schema on the DB Mapping: if selected, the underlying Database schema is updated on
every upload
– on the DB Mapping tab for each end:
* Excluded from auditing: if true, the relationship end is excluded from revision history keeping
of shared Records.
* Cache Region: name of the cache region of the relationship
– on the Foreign keys tab for each end:
2.12 Data Type Model
199
* Foreign Key Name: If such a name corresponds to the name of a primary key Field of that
shared Record, the foreign key is used as primary key. The types of the primary key and of the
foreign key have to match.
• Ends to non-shared Records from shared Records define the target column name and BLOB size
reserved for the database entry of the non-shared Record.
Important: It is not possible to increase the BLOB size in an existing database schema.
Figure 2.148 Data Relationship with composition
2.12.6.1
Deleting Record Instances in a Data Relationship
The deletion of record instances in a relationship, behaves depending on the relationship multiplicity as follows:
• If the relationship has the single multiplicity, if the instance is deleted, the entire instance takes the value null.
Figure 2.149 Deleting Record without multiplicity
Similarly, if the relationship has the single multiplicity, the deleted target record instance takes the value null.
Figure 2.150 Deleting Target Record Instance in the Single Relationship
• If the relationship has the set or list multiplicity, the deleted record instance of the set or list is removed from
the relationship (the list or set record instance with the null value is removed).
200
Modeling
Figure 2.151 Deleting Target Record Instance in the Set Relationship
2.12.6.2
Creating Record Components
Record components comprise the given record and the related Record in a "fixed" combination: you can create
such a relationship with the composition attribute set on the required data relationship ends. Mind that you can do
so only on a relationship end with single multiplicity.
If an end of a data relationship has the composition attribute, the following applies:
• When deleted, also the related records of the other end are deleted.
• When the other end is deleted from the collection, the record instance itself is deleted.
2.12.7
Creating an Interface
An Interface is defined as a special type of Record with no Fields or Associations. Records that implement the
Interface are connected to it with a Realization connector.
To create an Interface and its implementations, do the following:
1. Create the Interface Record:
(a) Create or open a Record that represents the Interface.
(b) In the Properties view of the Record, select the Interface checkbox.
(c) Create the methods file with the Interface methods: Right-click the Interface and click New Methods
File.
1 Nameable {
2
3
public String getName();
4
public void setName(String name);
5 }
2. To create a Record that implements the Interface, do the following:
(a) Create the Record and connect it with its Interface with the Realization connector.
(b) Right-click the Record and select New Methods Definition.
(c) Implement the Interface methods for the Record.
2.12 Data Type Model
201
Note: You can get to the methods file from the Interface Record by pressing Ctrl and double-clicking
the method in the Record diagram elements (to display the methods in your Record, right-click the
Record, go to Compartments and select Methods).
Figure 2.152 Interface with an implementation
2.12.8
Comparing Records
By default, a Record instance resolves into its object identities: if you compare records, the system compares the
objects' identities, not their field values. However, you might need to compare Records only by comparing some of
their Fields: since the structure of a Record is complex, you will need to define, which Fields will be used to identify
if two Record instances equal and possible include involved Relationships.
2.12.8.1
Defining Fields Used in Record Comparisons
Consider two instances r1 and r2 of record Record. Record defines a String field property.
1 def Record2 r1 := new Record2(property -> "string");
2 def Record2 r2 := new Record2(property -> "string");
3 r1 == r2
The code returns false by default since it checks whether r1 and r2 are the same record instances, which they are
not.
On the other hand, if you compare fields of a basic data type, the system compares the instances directly. Hence
r1.property == r2.property returns true.
202
Modeling
To compare one or multiple properties when comparing record instances instead of the record identities, set the
relevant record fields to Used for equals. If you set the flag on the Record String property,r1 == r2 would
compare the strings and return true.
If a record has multiple properties with the Used for equals flag, all properties must be evaluated as equal for the
record comparison to return true.
Note that the flag is inherited by fields of child records. For records with relationships to other records, you need to
set the Used for equals flag on the navigation to allow inheritance of the equals flags.
Important: The Used for equals flag applies only to non-shared records.
2.12.8.2
Using Fields on Related Records Used in Record Comparisons
To use a related Record when comparing a Record, select the Used for equals flag on the Relationship end.
2.12.9
Working with Record Diagrams
2.12.9.1
Displaying and Hiding Additional Compartments in Records
To display or hide additional compartments in Record views, such as, their methods, inherited methods,x Fields
and inherited Fields, right-click the Record view in the Diagram, go to Compartments and select or unselect the
compartments.
You can then click the method compartment to open its declaration.
Figure 2.153 Available Record compartments
2.12 Data Type Model
2.12.9.2
203
Viewing Record Hierarchy
You can view the record hierarchy of the entire workspace as one tree structure in the Type Hierarchy view.
The view provides an overview of all data types and their inheritance relationships. Note that the view is not
displayed by default: to display it, go to Window > Show View, or call the view from the context menu of a data
type (either in the GO-BPMN Explorer or the Data Type Editor).
The lower part of the view displays the Fields of the Record selected above and its data type.
Through the context menu of a data type, you can do the following:
• Open the Data Type Editor with the data type focused
• Show the Data Type in the GO-BPMN Explorer or Properties view
• Show Full Type Names for all displayed Data Types
• Focus On the selected Data Type to show only the particular Data Type and its hierarchy
Figure 2.154 Displaying a data type in the Record Hierarchy view (using the context menu) with the Record
Hierarchy view on the left
204
Modeling
2.12.10
Importing Data Types from an XSD File
To import the definitions in an XSD file as Records, do the following:
1. In the GO-BPMN Explorer view, right-click the GO-BPMN module.
2. Click Generate Data Types from Xsd.
3. In the Generate Types from Xsd dialog box:
(a) Select the Xsd file from the file system.
(b) Click Finish.
Some mechanisms of the XSD file such as reducing the set of the permitted values or allowing a choice of
values for several types are not supported.
2.12.11
Validating Record Values
Record value validation serves to check if values of Record instances and their Fields are correct: Whether a value
is correct depends on whether it meets the rules defined by the constraints of the underlying Record or Record
Field.
Constraints serve to map a Record or a Field to a particular constraint type. It is the constraint type that holds the
semantics of the validation—for the constraint to be met, the value of the Record or Field must satisfy the condition
defined in the constraint type.
An example of a constraint type is the NotNull() constraint type available in the Standard Library: it can be
applied to any object and checks if the object is null.
For example, you could define a constraint that binds the doesNotContainDigits constraint type to a record
field givenName. Or you could define your own constraint type isISBN with a constraint expression that checks
if a value is in the ISBN format and then a constraint that would bind it to such record fields as Book.ISBN or
Journal.ISBN.
Constraints are checked with the validate() function: The function returns a list of violated constraints on the
given record or field:
• When called over a record field instance, all constraints defined for the record field within the model are
validated.
• When called over a record instance, all constraints on the record's fields, the record itself, and its super types
are validated and that in this order.
The validate() function returns a list of constraint violations: each failed constraint is added to the list as a
ConstraintViolation object with a message returned by the constraint expression of their constraint type, the record
instance that failed the validation, and their constraint definition.
When validating Record data from a form, the violation messages can be then displayed in the form with the show←-
DataErrorMessages() function.
To provide additional granularity to validation, the validate() call can have tags as its arguments: on validation,
the constraint is applied only if the tags of the validate() call are identical to the constraint's tags expression. This
applies only if any of the constraints for the record or record field define a tag expression. If the constraints do not
contain any tags, they are applied on any validate() call.
2.12 Data Type Model
205
Figure 2.155 Validating record value using constraints
2.12.11.1
Defining Constraints
To define a constraint for a Record or a Record Field, do the following:
1. Open or create a constraint definition file.
2. In the constraint editor, do the following:
(a) In the Constraint area, click Add.
(b) In the Constraint Details area, define the constraint details:
• ID: unique identifier of the constraint It is recommended to use IDs in the format <Record←Name>.<FieldName>.<ConstraintTypeName>, such as, Book.ISBN.Format,
Book.ISBN.NotNull, ISIN.IsNumber, ISIN.HasMinLength, etc.
• Record (property): record or record Field to which the constraint applies Use the dot operator to
use records or record Fields on Data Relationship ends.
• Tags: expression that results in a list of tags Tags serve to filter constraints that are applied on
validation of the Record or Record Field.
Example Tag expression
1 tag1 and (tag2 or tag3) and not tag4
• Constraint type: constraint type that defines the constraint expression, type, parameters
206
Modeling
Figure 2.156 Defining constraints
2.12.11.2
Defining Constraint Types
Note: The Standard Library contains a rich set of constraint types. Hence check the <a href="../stdlib/index.html>available constraint types before you define your custom constraint type.
To define a constraint type, do the following:
1. Open or create a constraint type definition file.
2. In the constraint type editor, do the following:
(a) In the Constraint Types area, click Add.
(b) In the Constraint Type Details area, define the constraint type details.
Every constraint type defines the following properties:
• Name: name of the constraint type The constraint type name should refer to what is validated, for example,
IsEmail, IsNumber, HasMinLength, etc.
• Applied to: data type to which the constraint type can apply
2.12 Data Type Model
207
• Type parameters: Type parameters allow constraint type to operate over a parameter that can be of various
data types, not only a single data type, in different calls. The concept is based on generics as used in Java.
You can also make a generic data type extend another data type with the extends keyword. The syntax
is then <type_param_1> extends <type1>, <type_param_2> extends <type2> (for
details, refer to the Expression Language User Guide).
• Parameters: input parameters of the constraint type
The following parameters are provided by default and cannot be deleted:
– value: input object value
– context: additional data that can be passed as parameters
The context parameter can be used instead of tags. It is an object of type Map<String, Object> and
when defined by the validate() call, the call cannot define any tag arguments.
– constraintId: ID of the constraint definition that calls the constraint
You can define additional parameters.
• Type: return type of the constraint expression
– simple: Expression return value is a String which represents the error message.
– complex: Expression return value is a list of ConstraintViolation objects or their subtype.
Complex types allow cascading validation when related records and records fields are validated as part
of the record validation.
• Expression: constraint check expression
If validation is successful, the expression must return null; if it fails, it must return either a ConstraintViolation
object when Type is set to simple or a list of ConstraintViolation objects when Type is complex.
Figure 2.157 Defining constraint type
2.12.11.3
Filtering Applied Constraints using Tags
A constraint can define a tag expression, which must evaluate to true for the constraint to be applied: The tag
expression serves as a filter on constraints. When the validate() function is called, the constraint definition is
invoked only if the validate() call contains at least one of the constraint's tags as its argument. If the constraints do
not contain any tags, they are applied on any validate() call of the Record or Record field.
Validation tags can contain subtags. They allow you to create hierarchical tags: if a tag contains a collection of
subtags, the tag is considered a union of its subtags. For example, if a tag Car defines subtags ProductionYear and
Model, the tag Car is resolved into the ProductionYear and Model tags on validate() call.
208
Modeling
2.12.11.3.1
Defining Tags
To define tags, do the following:
1. Create a Validation Tag Definition (right-click your module, then click New -> Validation Tag Definition)
2. Double-click the definition to open it in the Validation Tag Editor.
3. In the Validation Tags area, click Add.
4. In the Validation Tag Details area, define the tag's properties.
2.13
Persistent Data
Under normal circumstances, record data ceases to exit as soon as the model instance ceases to exit. If you want
to persist Records, mark them as shared: a shared Record and the data on its Relationships are reflected in the
database.
Its runtime values are stored in the relevant database table immediately: any readings, modifications, and deletions
of shared Record values are reflected in the mapped database entry. To prevent the reflection, consider using
Change Proxy.
Note: Note that variables of a shared record type hold a reference to the shared Record values and
must be fetched anew in each new transaction the value must be fetched anew: You might want to
consider the performance aspect (for details on model transactions, refer to the Custom Process
Application Guide).
Persistence of shared Records makes use of Hibernate: Based on the data models, the system generates the
respective tables and a single common Hibernate setting file: as a consequence, if you upload multiple versions of
a data type hierarchy in multiple modules, only the last data type model is used.
If you modify the data type hierarchy, you have to decide how to handle the changes in the database: this is set by
the Database Schema Update Strategy of your server connection. You can also allow schema update per Record.
2.13.1
Defining Database Properties
Each data type definition can specify properties that define the database where the respective tables based on the
data type hierarchy are persisted. You can define the properties in the Properties view after you click the data type
root in the Outline View:
• Database: JNDI name of the data source used for the persisted database
This allows you to store the instances of shared Records in another database accessible to your application
server.
• Table name prefix: prefix used in the name of database tables created based on this data type definition
It is good practise to use a prefix so you can then easily find your tables. Note that you can check the prefixed
table name for individual Records and Relationship in their Properties view.
• Foreign key name prefix: prefix for the names of the foreign key columns created based on this data type
definition
• Index name prefix: prefix of index column name created based on this data type definition
2.13 Persistent Data
209
• Table name suffix: suffix used in the name of database tables created based on this data type definition
• Foreign key name suffix: suffix for the names of the foreign key columns created based on this data type
definition
• Index name suffix: suffix of index column name created based on this data type definition
To change the properties of a data types in a definition file, such as, target database, table names, foreign key
names, and index name prefixes, do the following:
1. Open the datatypes definition for editing.
2. In the Outline view, select the root Data Types item.
3. In the Properties windows, change the property values.
Figure 2.158 Defining database properties for a data type hierarchy
2.13.1.1
Extracting Shared Record Properties to Datatype Definition
If a data type definition contains shared Records with a common prefix or suffix in the target table name (on the
DB Mapping tab of the Properties view), you can extract the prefix to be set for the entire data type definition. This
allows you to extract such a prefix and keep it defined in one place.
To extract prefixes from a database with shared records, do the following:
1. In GO-BPMN Explorer, click the data types file.
2. In Outline view, click the Data Types root node.
3. In the Properties windows, open the Detail tab.
4. Click the Extract button.
5. Modify the prefixes are required and click Apply.
210
2.13.2
Modeling
Generating Data Model from a Database Schema
Generating of data types based on a database schema is governed by the same principle as binding of shared
Records onto a database schema (refer to GO-BPMN Modeling Language Specification).
To generate a data type model from a database schema, do the following:
1. Connect to the server with the data source.
2. In the GO-BPMN Explorer view, right-click the GO-BPMN module.
3. Click Generate Types from DB Schema.
4. In the Generate Types from DB Schema dialog box, select the data source and click Next.
If the data source is not listed, click New and define its properties.
5. Select the database schema and click Next.
6. Select the tables and columns to be included in the data type model.
Figure 2.159 Selection of Database Entities
7. Select the target location and enter the resource name, and click Finish.
Note the following limitations:
2.13 Persistent Data
211
• The generated data type definition does not generate any Diagram depiction of the shared Records: you
can pull and drag the shared Records from the GO-BPMN Explorer onto the data type canvas to create such
depictions.
• If the tool fails to detect that a shared record for a table already exists in the module and generates a new
record. Consequently, if a record that is being generated has a relationship to an already existing record, the
relationship is not generated either.
• Fields of generated records are sorted randomly.
Figure 2.160 Adding a depiction of a generated shared record onto a data type diagram
2.13.3
Creating Shared Records
Shared records are defined as records with the shared flag. Their database properties are defined on their data type
definition as well as on the shared Records and data relationships (Database Properties on Datatype Definitions
and Shared Record Attributes).
A shared Record defines the same properties as a common Record plus the following persistence-related
properties:
• Database Mapping:
– Table name: target database table
– Schema: target database schema
– Catalog: target database catalog
– Batch size: number of fetched entities from the database when the record is accessed from its related
record (Fetching)
– Cache Region: cache region of the shared record
– O-R inheritance mapping: available only if the shared record is the supertype of others.
* Each record to own table: maps each shared record in the hierarchy as its own table
212
Modeling
* Single table per hierarchy: a single table that unifies properties of all sub-records is used to store
the hierarchy. This option is convenient if you plan to query the database based on the Record
type. For this option, you can specify the name of a DB column name that discriminates the type
(the default values is TYPE_ID).
– Inheritance FK name: name of the Foreign Key used on inheritance
– Update schema: if true, the existing table schema is to be updated using the current schema
• Indexes: indexes on the related table of the Records
Important: When working with shared Records that are a target or source of a relationship, make
sure to define indexes for the foreign keys on the Records and their Relationship to prevent potential
performance issues. Note that you can generate the indexes in the data types file automatically: rightclick the canvas of your Record diagram and select Generate Indexes.
2.13.4
Creating Shared Record Fields
To create a Record Field in a shared Record, do the following:
1. Select the shared Record or its Field and press the Insert key to add a new Field.
2. Select the Field and define its generic properties on the Detail tab of its Properties view.
3. Define the database-related attributes on the DB Mapping tab:
• Column name: name of the mapped database column (The target database table is defined in the
parent shared Record.)
• Text length: the maximum length of the database entry for Fields that contain a String value
• Precision: maximum number of digits for Fields of the Decimal and Integer data types
• Scale: number of digits after the decimal poin for Fields of the Decimal data type
Note: When writing values into the Fields, Decimal Fields behaves like Java's BigDecimal.
• Unique: When generating the database schema of the data model, the Field will be translated into a
column with unique values.
• Version: if true, the engine ensures that an update of the current shared record is a modification of the
latest persisted version. It can be applied only to fields of types Integer or Date. Values of this shared
record field are directly managed by the engine.
• Exclude from optimistic lock: if selected the version of the Field entity in the database remains unchanged when the relationship changes; hence, the entity will be changed by all commits without collision. If not selected, and the relationship end entity is changed by multiple users at once, the system
returns a "Conflict on entity" error.
• Not null: if true, the Field must not be null.
• Primary key: if true, the field is considered the primary key in the database table.
• Auto generated: if true, the Field value is generated automatically when the instance of the shared
record is created.
The attribute is available only for Fields that are simple primary keys with integer values. Depending on
the target database, either a sequencer is generated, or auto-incrementation is used.
• Sequence name: the database sequence to be used for the auto generated Field (if it does not exist, it
will be created)
Important: When creating a new record with a specified property that is set as auto-generated over
an H2 database, the system will silently ignore the specified value and use the auto-generated value.
For example, if a shared Record Book defines the field ID that is auto-generated and you instantiate a
new Book as new Book (id->1), the ID value 1 will be ignored and the auto-generated ID will be
used instead. On other databases, such a code causes an exception.
Note: Shared Fields should contain only simple data type values. If a Field of a shared Record is of a
complex data type, consider creating another shared Record and connect it with a Relationship.
2.13 Persistent Data
2.13.4.1
213
Defining a Shared Field with a Foreign Key of a Related Record
To allow for a more efficient recovery of IDs of related shared Records, you can define as the column name the
foreign key of the Relationship end. You will need to do the following:
1. Name the Relationship end targeted to the related Record.
2. On the target Record, define a primary key Field.
3. On the Foreign Keys tab of the Relationship properties, check and possibly modify the foreign key of the
primary key Field.
Figure 2.161 Foreign key on the Relationship end
4. On the source Record, create a read-only Field that will be mapped to the foreign key.
214
Modeling
Figure 2.162 DB mapping of the Field
5. On the DB Mapping tab of the Field, insert the name of the foreign key column.
Now you can access the primary key of the related shared Record using the read-only Field.
Such foreign key fields if set as a primary key are set automatically when the related record is assigned. For
example, if Parent has a relationship to Child and one of the Child's primary-key fields is mapped to the primary key
of Parent, the field is automatically filled with the Parent id:
1 def MyParent p1 := new MyParent();
2 def MyChild c1 := new MyChild(id -> 1, parent -> p1);
Note that you need to make the relationship with the parent object: do not assign the foreign key directly as, for
example, new MyChild(id -> 1, parentId -> p1.id);
2.13.5
Data Relationships Between Shared Records
Data Relationships between Records establish a relationship between the Record tables. Unlike in JPA, the Relationship is symmetrical (set on both ends of the relationship) and hence it is not necessary to make one of the tables
the Owner.
2.13.5.1
Fetching
Fetching properties of Record Relationships define when the value of the related shared Record is fetched: a
related Record can be fetched either immediately along with the source Record or later when the related Record is
accessed. Values of all shared Records are fetched anew in every transaction of a model instance (for information
on model instance transactions, refer to Software Development Kit Guide).
Fetching strategy is defined on any named data relationship end and can be set to eager or lazy:
2.13 Persistent Data
215
• Eager: related shared records are fetched immediately when the source record is accessed.
• Lazy: related records are fetched only when they are explicitly accessed via their data relationship
(source.relationshipname)
Lazy fetching must define its batch size. Batch size is interpreted differently depending on the multiplicity of
the relationship end:
– For to-one relationship, batch size defines how many of the related records are fetched for the parent
records by the generated database selects.
– For to-many relationships, batch size defines for how many of the parent records all the related records
are fetched by the generated database select. Batch size for to-one ends is defined directly on the
record (refer to Defining Fetching on Single End Data Relationships and Defining Fetching on To-Many
Data Relationships).
2.13.5.2
Indexes
To allow quick look-up of shared Records in relationships, create indexes of foreign keys for the underlying database
tables: you can do so directly in the database or you can define the indexes using PDS.
Important: Absence of indexes for your shared Records can cause performance issues. Make sure to
define indexes to prevent slow search on your database data.
To define indexes for a table of a shared Record from PDS, do the following:
1. Display the properties of the record in the Properties view: click the record either in the GO-BPMN Explorer
or in the record diagram.
2. In the Properties view, open the Indexes tab.
3. Click the Add button on the right.
4. In the Database Index dialog, select the column that should be indexed and click > to add it to the indexed
column.
216
Modeling
Figure 2.163 Defining index
5. Upload the Module.
2.13.5.2.1
Generating Indexes
To generate indexes on foreign keys for all shared records that are related to another record in the data types file,
right-click the file in GO-BPMN Explorer and click the Generate Indexes button in the Properties view; alternatively
you can right-click into the canvas in a Record diagram and select Generate Indexes.
2.13.6
Auditing
Auditing of Shared Records refers to storing revisions of shared Records: When a shared Record is subject to
auditing, the system stores individual revisions of its instances so you can work with their previous versions using
the auditing functions of the Standard Library.
To save the revision IDs and revision timestamps, auditing uses the shared Record Revision Entity. You can then
use the respective functions of the Standard Library to look up individual revisions.
If you need to look up all entities that changed in one particular revision, consider adding a shared Record with the
entities modified by the given revision to Revision Entity.
Note: To store additional revision-related information, modify the underlying
data model, that is, either add new Fields to the Revision Entity Record or create a related shared
Record.
2.13 Persistent Data
2.13.6.1
217
Setting up Auditing
To set up auditing, do the following:
1. Create a shared Record that will be used as the Revision Entity: the record represents the table that will store
revisions.
2. On its Auditing tab in the Properties view, select the Revision entity option.
3. Typically you will add also the timestamp Field to the Record to be able to request the timestamp from the
database: add a Field of type Integer or Date and set it as Revision timestamp on the Auditing tab in its
Properties view.
Important: Only one revision entity Record and modified entity name Record can exist on the
LSPS server.
Figure 2.164 Revision entity shared Record
Note: By default the Revision Entity uses the LSPS implementation of the Revision Listener to enter revision
data into the database table. The listener enters the id of the revision and optionally the timestamp into the
database table. If you want the system to enter further data about the revision, you need to implement your
own Revision Listener that will extend the LSPSRevisionListener class (refer to Entity Auditing).
4. Optionally, create a related shared Record that will hold the names of the entities changed in the given
revision:
(a) Create a shared Record related to your RevisionEntity Record.
(b) On the Relationship, name both Relationship ends and set its Multiplicity to Set.
(c) On the Auditing tab of the Record Properties view, select its Modified entity name property.
(d) Add a String field that will hold the name of the modified entity: On the Auditing tab of its Properties
view, select its Entity name property.
218
Modeling
Figure 2.165 Shared Record for the modified entities of a revision
5. Upload the Module.
6. Set the required shared Records as audited: open the Record's Properties and on the Auditing tab select the
Audited option and upload the Module.
2.13.6.2
Including a Shared Record in Auditing
To enable auditing of a shared Record, do the following:
1. Open the Record's Properties view.
2. On the Auditing tab:
(a) Select the Audited option.
(b) Optionally, in Audit table name, enter the name of the table that will hold the Record revisions.
By default, the table name is <RECORD_NAME>_AUD.
3. Upload the Module with the data model.
Note: Make sure that you have uploaded the Revision Entity shared Record to your server: the LSPS
database will contain the ENTITY_REVISION table.
2.13 Persistent Data
219
Figure 2.166 Audited shared Record
2.13.6.3
Excluding a Shared Field or Record from Auditing
If you want to exclude a Record Field from auditing, open its Properties and on the Auditing tab, select the Excluded
from auditing option.
220
Modeling
Figure 2.167 Field excluded from auditing
2.13.6.4
Excluding a Relationship End from Auditing
If you want to exclude a Record Relationship end from auditing, open the Relationship Properties and on the tab for
the Relationship end, either the Source tab or the Target tab, select the Excluded from auditing option.
2.13.6.5
Working with Record Revisions
To work with revisions of Record instances, use the provided Standard Library functions available in the Core
module:
• getRevisions() to obtain revisions of the Record instance created within a certain period of timestamps∗
• findByRevision() to obtain the Record instance in a particular revisions
• getCurrentRevision() to get the current revision of an Entity
2.13.7
Caching Shared Records
To improve application's performance, define cache regions: cache regions keep in memory the instances of shared
Records that might be required by a particular model instance, user, as well as other users and transactions, which
reduces the load on the underlying database.
A cache region is added to the server cache based on the cache region configuration on module upload.
Note: LSPS applies first-level caching within individual transactions, that is, any data is cached within
a transactions. The cache regions implement second-level caching that is applied on shared Records.
The cache exists regardless of the instance transaction or model instance life.
2.13 Persistent Data
2.13.7.1
221
Defining Cache Regions
Cache regions are defined in Cache Region Definition files: the files hold one or more cache region definitions. One
module can contain multiple cache region definitions.
To define a cache region, do the following:
1. In the GO-BPMN Explorer view, double-click the respective cache region definition. The Cache Region Editor
is opened in the editor area.
2. In the Cache Regions area, click Add.
3. In the Cache Region Details area, define the cache region attributes.
• Name: name of the cache region
• Database: JNDI database name on which the cache region is applied (for example, jdbc/my_database)
If undefined, the LSPS system database is used.
• Max elements in memory: maximum number of objects to keep in the memory cache
• Eternal: if true, the cached objects are not scheduled for discarding
– Time to idle: time in seconds an object remains cached if not accessed
– Time to live: seconds an object remains cached regardless of the accesses
• Overflow to disk: if true, the file system is used to store cached objects.
– Disk persistent: if true, the cache remains unchanged after the restart of the process engine.
– Disk expiry thread interval: interval for the cleaning of expired cached business objects in seconds
– Max elements on disk: maximum number of objects to keep in the disk cache
• Memory store eviction policy: If a memory store has a limited size, the objects will be evicted from the
memory when it exceeds this limit. The following strategies are available:
– LFU: The least frequently used objects are evicted.
– LRU: The least recently used objects are evicted.
– FIFO: objects are evicted in the same order as they are cached.
– Description: free text area to describe the cache region.
2.13.7.2
Disabling Cache Regions
To disable cache regions in your Modules, use the disabling mechanism.
If you need to disable the LSPS system cache regions, define the disabled cache regions in the <YOUR_C←USTOM_APP>-ejb/src/main/resources/cache-regions.properties file of your custom LSPS
application.
2.13.8
Change Proxy
If you want to save modifications of a shared Record instance and only later decide whether to apply or discard the
modifications, create a Change Proxy over your shared Record instance and change the data of this object instead:
the Change Proxy object hold your changes, while the original shared Record instance remains unchanged. You
can then either apply (merge) to the referenced Record instance.
Typically, you will do so when editing a Record in a form. Note that if you do not created a proxy, you will work with
the "real" Record instance in your form.
222
Modeling
Note: Proxy objects are not supported by forms created with the ui Module since these forms use the
evaluation context created with the View Model component.
When you create a Proxy object, the object is created on a Proxy level, which represents a layer over the "real data
layer". If you create a Proxy object of another Proxy object, the new Proxy object is created on yet another Proxy
level that overlays the already-existing Proxy level, etc.
Individual Proxy objects can see only data in their own Proxy level and the Proxy levels of their parent: all Proxy
objects can see the original Record instance and any Proxies in the levels above, while they cannot access or see
any Proxy objects created for them.
Figure 2.168 Proxy levels: Proxy object of My Record Instance exists on Proxy Level 1. It can see the
Record instance and any other data within the given context. A Proxy of the Proxy lives in Proxy Level 2: It
can see Proxy Level 1 and the original record; the Proxy of My Record instance cannot see Proxy Level 2.
Note: When designing Forms that make use of Proxy objects, consider creating and merging objects
out of your Form definition: This will keep your Form definition easier to maintain and reuse since it will
hold only the presentation logic. You can do so by defining a parametric constructor that will take the
logic-related arguments, such as, Proxy objects, and action handlers.
Example of a constructor call
1 new EditPersonaForm(
2
//argument is already a Proxy of the edited Person object:
3
proxy(john),
4
//argument is the stored in the Form local variable
5
//and used in the Click Listener closure:
6
{ edited:Persona -> mergeProxies(edited)})
For usage examples, refer to Creating a Model Popup and Creating a Public Popup.
2.13 Persistent Data
2.13.8.1
223
Creating Proxies
When you create a Proxy object of a shared Record instance, the system creates an object with a reference to the
shared Record instance. This proxy exists on the Proxy level separated from the base level: Any changes performed
on the Proxy object are stored on this level and can be merged into the original shared Record instances on the
base level whenever required.
To create a Proxy object, use the proxy() function with the required parameters:
• proxy(<OriginalRecordInstance>, <PropertiesOfRelatedRecords>, ..) creates
Proxy of the shared Record instance and Properties of the related Records (for example, proxy(Jane,
Person.address))
If you do not create a proxy of a related shared record, when you navigate through the proxy to the non-proxied
record, the system will access the underlying Record.
For example, let us assume a record hierarchy multiple related records.
We have the following proxy:
1 //Original shared record instance:
2 def Persona persona :=
3
new Persona(name -> "Night Mare",
4
address -> new Address(street -> new Street(number -> 0, name -> "Elm Street")),
5
documents -> new DocumentIDs(
6
driversLicense -> "A000-0000-0000",
7
insuranceNumber -> "000-00-0000-A",
8
passport -> "00000000")
9
)
10 //Proxy:
11 def Persona proxyPersona := proxy(person, Persona.address);
We have created only a proxy object of the Persona record and its related Address record. If we access
its documents via proxyPersona.documents, we will access the Record Address directly: to create a
proxy of such a related record, add the property to the proxy() call:
1 def Persona proxyPersona := proxy(persona, Persona.address, Persona.documents);
The Streets record cannot be proxied from the person.
• proxy(Collection<RecordInstances>, <PropertiesOfRelatedRecords>, ..)
creates Proxy of the Record instances and the related Records (for example, proxy([Jane, John],
Persona.address);
• proxy(SharedRecord) creates Proxy of a Shared Record without an underlying Record instance: this
allows you to abandon the Proxy without actually creating the Shared Record instance; proxy(shared←Person) will not result in any persistent data. Typically, you will use the call in the preCreateWidget()
method of a form to operate from the form over proxies.
224
Modeling
2.13.8.2
Creating Proxies of Records with Relationships
If you want to create a proxy of a Record with a related Record, that is, without creating the "real" Record instances,
we recommend to do the following:
1. Create a variable that will hold the proxy of the Record, for example, def Author author :=
proxy(Author)
2. Create the related proxy from the variable using the dot operator, for example, author.book :=
proxy(Book)
2.13.8.3
Merging Proxies
When you merge a Proxy object, the changes stored in the Proxy as well as changes on the properties of the object
are applied on the objects located one Proxy level above or into all levels above.
To merge Proxies or to create the proxied shared Record, use the merge function with the required parameters:
• variadic mergeProxies(RecordInstance1, ..) and mergeAllProxies(List<Record←Instances>) merges the changes on the Record instances into the original Record instances or parent
Proxy.
• variadic mergeProxiesDeep(RecordInstance1, ..) and mergeAllProxiesDeep(List<Record←Instances>) merges the changes on the proxy Record instances and their proxy Properties into the
original Record instances and any related Record instances.
For example, in the case of the proxy of an author with a book, mergeProxiesDeep() would merge the
author proxy as well as its related book proxy.
If you assign to a proxied property an object from a higher proxy level, on merge, the association is applied on the
target object: the original Relationship is removed.
2.14
Constants
A Constant is a variable with a value of a basic data type, the enumeration data type, or maps of the these data
types. After the value has been initialized, it remains unchanged in its context. A constant can call other constants
when initialized.
Note: Constants are initialized before model variables and all model variables return the value null.
Therefore make sure not to use any context data when initializing constants.
To define a constant, do the following:
1. In the GO-BPMN Explorer view, double-click the respective constant definition.
2. In the Constants area of the displayed editor, click Add.
3. In the Constant Details area, define the constant attributes.
To call your constant in an expression, write its name.
2.15 Webservices
2.15
225
Webservices
In Process Design Suite you can define processes that serve as web-service servers or clients: The procedures
differ slightly depending on whether you are working with SOAP or RESTful web services.
2.15.1
REST Webservices
You can create a process that will act as RESTful Web Service server or client using dedicated task types:
• server: tasks generated based on the RESTful definition
• client: HttpCall task type
The RESTful Web Services are implemented as required by JAX-RS: Java TM API for RESTful Web Services
version 2.0 Final Release.
2.15.1.1
REST Webservice Server
To create a Process that will handle REST requests, you need to create a definition and generate task types based
on the definition. The task types will then serve to design the Process.
A Process that acts as a REST server, uses the following tasks in its workflow:
waitRestRequest waits until it receives a web service request from client: it accepts a request if the path of the
request matches its path template. If there are several tasks waiting for a request then the task with a more
precise path template handles the request. Once a task accepts the request, it finishes, and the process
instance execution proceeds.
The waitRestRequest task defines the following parameters:
• input: input received from the client
• requestId: ID of the call
The ID is used by the response tasks to identify the call; the value is generated by the LSPS Server.
• parameters with path variables as defined in the web-service definition
• htttpHeaders (optional): parameter with received HTTP header
• requestParams (optional): parameter with received request parameters
sendRestResponse sends a response to the request with the request ID defined by its parameter.
The task defines the following parameters:
• output: response sent to the client
• requestId: ID of the call
sendRestErrorResponse sends a fault message to the client when the received request call is evaluated as
incorrect or fails.
The task defines the following parameters:
• error: error sent in the error response to the client
• requestId: reference to the ID of the call
226
Modeling
2.15.1.1.1
Creating REST Server
To create a REST web service server process, do the following:
1. Create the records for the server:
• input record for data received from the web service client
• output record for data sent as a response to the web service client
• error record for data sent to the client as an error
If you want to use JSON as your content type, make sure the properties of the records are only of the
following types:
– String, Integer, Decimal, Boolean, Date, or Enumeration.
– Set, List, Map with String, Integer, Decimal, Boolean, Date, Enumeration members, or Set, List,
Map members with members of these types.
– References to records with properties of the types as defined above.
2. Create a web service definition file:
(a) Right-click the Module, go to New > RESTful Webservice Definition
(b) Open the file in the web service editor and define the web service properties:
• Path Template: template of the URL path of the service
Define the Path Template with any path variables you want to use: the variables will be added to the
Path Variables table below automatically. The template supports path variables, such as, {item←ID}, and regular expressions. The REST server URL is then resolved as <LSPS_Server_U←RL>/lsps-ws/rest/<Path_Template> and path variables are accessible as parameters
of the waitRestRequest task.
• Method: method type
• Input type: input record
• Output type: output record
• Error type: error record
• In the Path Variables table, adjust the data type of individual variables: the generated task types
will have the variables as parameters.
(c) If applicable, select Generate optional parameters for access to HTTP headers: if selected, the generated task type will contain the responseHeaders parameter so you can modify the response headers;
otherwise, you will be able to use only the default headers.
(d) If applicable, select Generate optional parameters for access to HTTP request parameters: if selected,
the generated task type will contain the requestHeaders parameter so you can modify the request
headers; otherwise, you will be able to use only the default headers.
(e) Save and click Generate:
The system generates REST webservice server task types.
3. Design the process workflow with the generated task types.
Consider global variables for the input, output, and error data types that will hold the data during the web
service invocation.
2.15 Webservices
227
Figure 2.169 REST Server Process
4. Deploy the Model with the Process and run its instances as necessary.
Important: If the timeout period elapses and the server has not sent any response, the server sends
a timeout response to the client. The default time out is set to 10 seconds.
2.15.1.2
REST Client
To create a Process that will serve as a REST client, use in the workflow the HttpCall task type or use your own
task type.
Make sure to define all required parameters of the task.
Example HTTPCall task parameters
1 httpMethod /* String */ -> "POST"
2 ,
3 url /* String */ -> "http://localhost:8080/lsps-ws/rest/client/123"
4 ,
5 request /* Object */ -> convertToJson(new Input(int -> 333))
6 ,
7 requestContentType /* String */ -> "application/json" //"application/xml"
8 ,
9 response /* Reference<String> */ -> &response
10 ,
11 responseCode /* Reference<Integer> */ -> &responseCode
12 ,
228
13
14
15
16
17
18
19
20
21
22
23
Modeling
login /* String */ -> "admin"
,
password /* String */ -> "admin"
,
readTimeout /* Integer: timeout in ms */ -> 9999
,
requestHeaders /* Map<String,String> */ -> [ "Accept" -> "application/json"]
,
responseHeaders /* Reference<Map<String,String>> */ ->
,
isSynchronous /* Boolean */ -> false
2.15.2
SOAP Webservices
To implement a process that will serve as a SOAP server or client, you need to create the resources that represent
the web service operations and design the web-service process.
Process Design Suite supports communication with other systems via SOAP web services: Generally you will need
to generate Task types that can be used to design Processes that act either as a Web Service Server or a Web
Service Client):
• Web-service client tasks:
– For every operation, the system generates one task type that sends a request to the web service server,
and receives the response.
• Web-service server tasks:
– Wait task that waits for a request from a client,
– Response task that sends a response to the client,
– Error task that sends a fault response to the client.
2.15.2.1
SOAP Server
To be able to implement a Process that will serve as a SOAP web-service server, you will need to generate task
types that can handle the client web-service call and create a process with the tasks of these types that will serve
such client requests with the tasks of these types:
waitForInvoke waits until it receives a web service client call: Once the task has received a client call, the task
stores the client input and finishes.
The task defines the following parameters:
• input: input of the call from the client request
• requestId: reference to the ID of the call
The ID is used by the response tasks to identify the call; the value is generated by the Execution Engine.
• principal: reference to a slot that holds the principal who is performing the call
• logXmlMessage: if true, all XML messages received by the task are logged to the database and can
be viewed in the Webservices.
Important: Enabling logging of XML messages can result in significant database growth.
Make sure to handle such risks appropriately.
• requestHeaders: reference to a slot that holds the HTTP headers of the request
sendResponseToInvoke sends a response to the wait point of the request ID.
The task defines the following parameters:
• output: output sent in the client response
2.15 Webservices
229
• requestId: reference to the ID of the call
• logXmlMessage: if true, all XML messages received by the task are logged to the database and can
be viewed in the Webservices.
Important: Enabling logging of XML messages can result in significant database growth.
Make sure to handle such risks appropriately.
• requestHeaders: reference to a slot that holds the HTTP headers of the request
sendErrorToInvoke sends a fault message to the client in cases the received request call should be considered
incorrect or failed.
For error responses, the task defines the following parameters:
• error: error sent in the error response to the client
• requestId: reference to the ID of the call
• logXmlMessage: if true, all XML messages received by the task are logged to the database and can
be viewed in the Webservices.
Important: Enabling logging of XML messages can result in significant database growth. Make
sure to handle such risks appropriately.
• requestHeaders: reference to a slot that holds the HTTP headers of the request
Depending on whether you have the WSDL file for the service, you will need to do the following:
• If you do not have the WSDL file, you need to model the input and output data types, and define a WSD
definition (Generating Tasks for Web Service Server). Based on the WSD definition, the system generates
the task types that you can use to implement a web service server in a process.
• If you already have a WSDL file, the system generates the data types and task types for the web service
server directly based on the WSDL file (refer to Generating Tasks for Web Service Server from WSDL File).
You can check and manage Model instances that are serving a web service call in the Web Services view in the
Management perspective or Web Management Console.
2.15.2.2
Creating SOAP Server from Scratch
To generate task types and design a process acting as a SOAP web-service server without a WSDL, do the
following:
1. Create the data types for the server.
• input: input data type received from the web service client
• output: output type of the data sent as a response to the web service client
• error: data types for data sent to the client as a web service error (when the client sends invalid data to
the server)
All these data types must be defined as Records even if they contain only primitive values since they will be
used in the WSDL and used for XML mapping in XSD.
2. Check the XML mapping of the Records, their Fields, and Relationships on the XML Mapping tab of their
Properties. The mapping will be applied in the XSD, WSDL files of the service, and potentially during any
XML parsing to the Records. Generally, the default mapping should work fine.
To exclude a Relationship direction from the XSD schema of your server, mark the relationship direction as
XML Transient: in the Properties view of the Relationship, select the Target XML Mapping or Source XML
Mapping tab and select XML Transient.
230
Modeling
3. Create a web service definition file:
(a) Right-click the Module, go to New > Webservice Definition
(b) Open the file in the web service editor and define the web service properties:
• Service name: name used as the service name and the task name in the generated task types
The target service URL is resolved as <LSPS_Server_URL>/lsps-ws/service/<MO←DULE_NAME>/<Service_Name>.
• Service namespace: namespace of the Web service used in the generated WSDL
• Input type: input data type you defined
• Output type: output data type you defined
• Soap fault types: fault data types you defined
(c) Select the options for applicable settings of headers.
(d) Click Generate:
The system generates the following:
• XSD schema file, which will make use of the data types
• WSDL file that imports the XSD schema.
• Webservice server task types
4. Design the server Process workflow with the generated task types.
Important: Make sure to define the id parameters on the waitForInvoke, sendResponseTo←Invoke, and sendResponseToInvoke. Failing to do so, might result in transaction rollback.
Figure 2.170 Workflow of a process serving as a web service server
5. Expose the WSDL and XSD files as appropriate.
2.15 Webservices
231
Important: If the timeout period elapses and the server has not sent any response, the server timeout
response is sent to the client. The default time out is set to 10 seconds.
2.15.2.2.1
Creating SOAP Server from WSDL
To generate task types and the underlying data types for web-service server from a WSDL file, do the following:
1. In the GO-BPMN Explorer, right-click the respective module and in the context menu click Generate > Webservice Server.
2. In the Generate Webservice Server dialog box, enter the following:
(a) In the WSDL location text field, type the location of the WSDL, possibly a URL.
(b) Select the optional task parameters for HTTP headers.
The system will create a copy of the WSDL in the Module and create the respective Records and task
types. Consider storing input, output, and error data types that will hold the data during the web service
invocation, in global variables.
Figure 2.171 Web Server Service Module
3. Design the process workflow with the generated Webservice-Server Tasks.
232
Modeling
Figure 2.172 Workflow of a Process Serving as a Web Service Server
4. Expose the WSDL and XSD files as appropriate.
2.15.2.3
SOAP Client
To design a Process that acts as a web service client, you will generate artifacts from based on the WSDL file of the
target web service. These will include the following:
• invoke task types for each operation: The tasks of the invoke task type perform the web service operation
calls.
• fault data types: Fault data types to store returned web service errors
• data types used by the generated task types
Note: Only SOAP 1.1 document and literal style Web services are supported.
Web Service Task Types
Every generated task type represents one WSDL operation with the operation's messages and related information
defined by its properties:
2.15 Webservices
233
• isSynchronous: if true the web service call is synchronous
If synchronous, the entire process execution stops until the server response is received.
If asynchronous, other parts of the process instance can continue their execution (other tokens in the process
continue their execution); for example, parallel branches continue, while the branch with the web service client
task waits for the server response.
• input: input data sent to the web service server
• requestHeaders: custom headers of the request
• requestSoapHeaders: soap headers sent with the request
• output: reference to a slot that stores the server response
• responseHeaders: reference to a slot that stores the response headers
• responseSoapHeaders: list of references to variables
The variables will be filled with the received soap headers if they match any of the present headers.
• endpointAddress: target webservice endpoint URL address
If null, the endpoint address from metadata is used.
• logXmlMessage: database logging of messages If true, all XML messages received by the task are logged to
the database (false by default).
Note: Enabling logging of XML messages can result in significant database growth.
• error: In case the web service server return soap: fault in web service response, fault is stored in this variable.
If null, soap fault is discarded.
• readTimeout: read timeout in milliseconds
After the defined time period elapses, a BPMError is thrown. You can handle the possible error with an Error
Intermediate Event. If undefined the timeout is set to zero (0) and hence no timeout is applied (the timeout is
infinite).
• login: login name used to access the web service
HTTP basic authentication is used.
• password: password for HTTP basic authentication
2.15.2.3.1
Creating SOAP Clients
Important: Resources for a web service client can be generated only for SOAP 1.1 web services.
To create data types and task types that will constitute you web-service client process, do the following:
1. Get the WSDL and any other related resources.
Web service WSDL is usually available on a URL provided by the web service server. When generating web
service client for web service server Process, include the required XSD files.
234
Modeling
2. In the GO-BPMN Explorer, right-click your Module and in the context menu, click Generate > Webservice
Client.
Figure 2.173 Generating artifacts for web service client
3. In the Generate Web Service Client dialog box:
(a) Enter the path to the target Module.
(b) In the WSDL location text field, type the URL or file system location of the WSDL.
(c) Select the options for the additional parameters: these will be generated as properties of the task types.
(d) Click OK.
(e) Select the required web-service operations: for every operation, one task type and the respective data
types will be generated. Tasks of the task type call the web-service and request the operation.
2.15 Webservices
235
Figure 2.174 Selecting relevant operations
(f) If necessary, adjust the XML mapping of the data types: open the Properties view of the record and on
the XML Mapping tab, change the mapping.
236
Modeling
Figure 2.175 Generated Task Types and Data Types
4. Design a process with the generated task types.
2.16 Jasper Reports Integration
237
Figure 2.176 Model instance of a web service client Process
2.16
Jasper Reports Integration
The primary support for Jasper Reports is provided by the reports Module of the Standard Library: the Module
contains the reports function definition with the following functions:
• jasperReportUrl() returns the URL of a Jasper Report on a Jasper server
• embeddedJasperReportUrl() returns the URL of the JasperReport in the LSPS Embedded Server
Note: The LSPS Embedded Server integrates the Jasper Report library; hence no Jasper Server is
called when working with the Embedded Server.
• jasperReportPDF() generates the PDF version of the report with the provided parameters
Note: The reports library is used by the bamLibrary that provides resources for a dashboard-style Business Intelligence Monitor dashboards. To create your own dashboard, you can modify the showcase
Business Activity Monitor document as required.
2.16.1
Mapping of Parameter Data Types
When you request a parametric Jasper report with one of the reports function of the Standard Library, on runtime,
the data type of the parameter value is converted to its Java equivalent:
238
Modeling
Expression Language Type
Java Type
String
java.lang.String
Integer
java.lang.Short∗
java.lang.Integer∗
java.lang.Long∗
java.lang.Float∗
java.lang.Double∗
java.math.BigDecimal
Decimal
java.lang.Short∗
java.lang.Integer∗
java.lang.Long∗
java.lang.Float∗
java.lang.Double∗
java.math.BigDecimal
2.16.2
Boolean
java.lang.Boolean
Date
java.util.Date
List∗∗
java.util.List
Set∗∗
java.util.Set
Integrating a Jasper Report with Process Application
To generate and access your report directly from the Process Applications, embed the target URL of your report
into a Form of a Document or User Task.
2.16.2.1
Displaying Jasper Report on the Embedded Server
You will typically display your report in a Browser Frame or navigate away from the Document or To-Do to the report
URL:
To display your report in a Browser Frame, do the following:
1. Copy the report jrxml file to your GO-BPMN project.
2. Open or create the Form definition.
3. Insert a Browser Frame component into the Form.
4. Define its URL property to the report using embeddedJasperReportUrl
• on a Browser Frame as target Url embeddedJasperReportUrl(thisModel().name, "←-
MyBamReport/HelloModel.jrxml", [ "editable"-> true])
• on a Listener of a component, such as a Button: Forms.navigateToUrl((embedded←-
JasperReportUrl(thisModel().name, "MyBamReport/HelloModel.jrxml", [
"editable" -> ])))
2.16 Jasper Reports Integration
2.16.2.2
239
Exporting a Jasper Report
To allow the user to export a Jasper Report into PDF, Excel, or Word and download, use the jasperReportExport()
in a form component, such as a Button: note that the function returns a File which you might want to handle further.
Example FileResource of a Download component with a PDF report
1 new FileResource(jasperReportExport(thisModel().name, "MyBamReport/HelloModel.jrxml", ReportFormat.pdf ,
[->]));
Example Click Listener of a Generate PDF button that generates the PDF report and sets the PDF Link
component properties
1 {e ->
2
def FileResource pdf :=
3
new FileResource(jasperReportExport(thisModel().name, "MyBamReport/HelloModel.jrxml",
ReportFormat.pdf, [->]));
4
PdfLinkComponent.setResource(pdf);
5
PdfLink.Component.setEnabled(true);
6 }
2.16.3
Integrating Process Application with a JasperServer
To work with Jasper Reports on a Jasper Server, use the jasperReportURL() to generate and obtain access to
reports on an external Jasper Server.
Example URL of a Browser Frame component that points to a report on a remote Jasper server with no
parameters
1 jasperReportUrl("http://myremoteserverip:9090/jasperserver", "jasperadmin", "jasperadmin",
"/reports/MyReports/myReport", false, ["topLimit"-> 120])
Important: Make sure to insert the full and correct path to your report.
Figure 2.177 Path of the report in the web client
240
Modeling
2.16.4
Enabling Expression Language in Jasper Reports
To enable data queries of Jasper Reports in Expression Language, do the following:
1. Add lsps-runtime/jasperreports-extension/lsps-tools-jasperreports-extension-<V←ERSION>.jar to the classpath of your Jasper server.
2. Set the property com.whitestein.lsps.datasource.url to point to base URL to the RESTful API
For the Embedded Server, this would be set to http://localhost:8080/lsps-monitoring-ws/resources/rep
3. Set the following parameters for your reports:
• query language to LspsExpression
• LSPS_MODULE_ID or LSPS_MODEL_INSTANCE_ID to define the context for the report data
• authentication data as LSPS_USERNAME and LSPS_PASSWORD
4. Define the data query in the Expression Language. Make sure the Expression returns a string with results in
a valid JSON format.
2.17
Monitoring
Monitoring features are provided by the Business Activity Monitor Library: with the library, you can create Documents
with dashboards that display widgets with Jasper Reports or forms. Dashboards can be shared among users and
users can set the parameters for parametric reports.
Business Activity Monitor capabilities are provided as a library. In addition, you can generate an example implementation of a BAM Application.
Important: Though the library is based on the forms module, its widget can make use of forms of the
ui module.
When creating data for monitoring, consider using (monitoring assignments and monitoring flags)[modelinglanguage/modelingelements.html#monitoring].
The example Business Activity Monitor application is build upon the bamLibrary library and provides an application
with the following reports:
• Activity Running Time: how long it takes to complete a task (human or non-human)
Only complete tasks are included: Instances of a looped task are considered part of a single task.
2.17 Monitoring
241
• Activity Utilization Ratio: how often an activity in a model was triggered in ratio to the number of the model's
instances
• Model Instances by Status: bar chart with models indicating the status of their model instances
Each bar represents all instances of a particular Model and is color-coded to indicate portions of instances in
different statuses.
• Person Utilization by Task: instances of a task sorted for persons who completed (submitted) them
• Plan Utilization Ratio: number of times individual plans of a goal were used to achieve the selected goal
• Process Running Time: average running time of finished process instances of the selected processes (note
that you can select multiple processes)
• Process Running Time Distribution: average running time of finished process instances of the selected
processes for a defined period of time
• Started Model Instances: line chart with the number of instance of selected models started during the
selected period
• Started Process Instances: line chart with the number of instance of selected Process started during the
selected period
• Users Activity Period: bar chart with times of activity of the front-end application users
The report is only available if the User Tracking feature is activated.
• Vaadin Chart Form: example widget with a form as its content
The application with its widgets is accessed via a document from the Process Application. Note that when you add
the widget to your dashboards, they will not contain any data: Define the report parameters to display a report.
242
2.17.1
Modeling
Generating and Deploying Business Activity Monitor Example
The example Business Activity Monitor application is a document with dashboards that can hold widgets with Jasper
Reports or forms. The application is created with the bamLibrary Module.
To generate and deploy the default Business Activity Monitor, do the following:
1. Create a GO-BPMN Project that will hold the BAM Module.
Make sure the project contains the BAM Library (to add the library, right-click the project and click Add
Library, and use the Select built-in library option.)
2. Go to File -> New -> Examples.
3. In the dialog box, select BAM Dashboard and click Next.
4. Select the target project and click Finish.
5. Make sure your server connection is up and running.
6. Upload the bam Module (right-click the Module, click Upload As, and Model).
7. To access Business Activity Monitor, log in to the Process Application, go to Documents and open the
Business Activity Monitor document.
Figure 2.178 Opening BAM document
In the document, you can create your dashboards or display public dashboards with their widgets.
2.17 Monitoring
243
Figure 2.179 Business Activity Monitor with a private dashboard displayed
2.17.1.1
Defining a Default Dashboard
To define a default dashboard that will be available to every user, do the following:
1. Create an executable module that will import the bam module.
2. Create a resource that will create the default dashboard, for example, a process with the code in an assignment of a process element. As part of the code, you need to do the following:
• Create or obtain the BAM users that should have the dashboard.
• Create the dashboard as a DashboardData object with its widgets.
• Add the dashboard to the list of the user's dashboards as a DashboardOrder object.
3. Run the module.
\\The dashboard is made available to the current user:
def BAMUser bamUser := getOrCreateCurrentBAMUser();
\\The dashboard instance with no widgets:
def DashboardData newDashboard := new DashboardData(name -> "DefaultPublicDashboard", author -> bamUser,
isPublic -> true);
5 newDashboard.widgets := [];
6
7 def TimePeriodParameter timePeriod := getParameterTimePeriod(1);
8 def Set<ModelParameter> allModels := findParameterModels().toSet();
9 def Set<Integer> modelIds := collect(allModels, {model:ModelParameter -> model.id});
10
11 def WidgetData startModelInstancesWidget := new WidgetData(
12
name -> "Started Model Instances",
13
moduleName -> "hll-reports",
14
caption -> "Started Model Instances",
15
x -> null,
16
y -> null,
1
2
3
4
244
17
18
19
20
21
22
23
24
25
26
Modeling
height -> 4,
width -> 3,
state -> null,
parameters -> [PARAM_TIME_PERIOD -> timePeriod.name,
PARAM_TIME_PERIOD_ID -> timePeriod.id,
PARAM_MODEL_IDS -> modelIds]
);
newDashboard.widgets := add(newDashboard.widgets, startModelInstancesWidget);
\\Add the dashboard to the list of dashboards:
new DashboardOrder(dashboard -> newDashboard, user -> bamUser)
2.17.2
Customizing Business Activity Monitor
To create a custom Business Activity Monitor, we recommend to start from the example Business Activity Monitor
application. However, you can create your Business Activity Monitor application from scratch as well.
Important: If you decide to modify or reuse the example Jasper Reports or create a new report that
will use a template of styles (in the example application it is LspsStyle.jbtx template), do not use
Jaspersoft® Studio 6.3.1 since it remains hanging due to an issue when loading the common template
of styles.
First generate the example BAM Dashboard with widgets:
1. Go to File -> New -> Examples.
2. In the dialog box, select BAM Dashboard and click Next.
3. Select the target project where you want to generate the application and click Finish.
The system generates the bam Module with the application resources with the following resources of interest:
• bam.docs: the document that creates the form with the dashboards
• Reports: folder with resources for individual widgets:
– Jasper Report displayed in the widget
– form definition of the dialog where the user changes the report parameters
– method definition with the methods for the widget including the getParameters() and methods that return
parameters for the report
– other resource, such as, localization, query definitions, etc.
2.17.2.1
Adding a Custom Widget with a Jasper Report
To add a custom widget that will display a Jasper Report to the Business Activity Monitor, do the following:
1. In the Reports folder of the bam module, create a folder for your widget.
Alternatively create the widget resources in a separate Module and import it into the bam Module.
2. Copy the Jasper Report into the folder and refresh the folder (select the folder in GO-BPMN Explorer and
press F5).
3. Create a form that will allow the user to define the report parameters:
• Typically you will use input components, such as Combo Box, Input Field, etc. Make sure to define IDs
for the input components, so you can acquire their value with the getParameters() method.
2.17 Monitoring
245
• Create a local variable of the ReportFrame type: the variable will hold reference to the ReportFrame
with the report when changing parameters.
• Create a component that will apply the parameters on the ReportFrame and refresh it, typically you will
use a button with the action defined as its click action:
1 {_ ->
2
reportFrame.setParameters(getParameters());
3
reportFrame.refresh()
4 }
4. In the methods file of your parameter Form, define the following methods:
• constructor with ReportFrame as its input parameters
1 public MyWidget(ReportFrame reportFrame) {
2 this.reportFrame := reportFrame
3 }
• getParameters() method, that will return the new parameters: The report parameters are defined as a
map of parameter names and their values.
1 private Map<String, Object> getParameters() {
2
//load the value from the input component into a local variable:
3
def String newParameterValue := myInputField.getValue();
4
//return the values mapped to their report keys:
5
[
6
"jasperReportParam" -> newParameterValue
7
]
8 }
• showReport() method that will display and update the report.
1 private void showReport() {
2
Forms.navigateToUrl(embeddedJasperReportUrl(thisModel().name,
3
"Reports/myReport.jrxml", getParameters()))
4 }
5. In the bam.docs, add the widget to the BamDocument UIDefinition:
1 new BamApplicationForm(new BamConfiguration(widgets ->[
2
new WidgetDefinition(
3
name -> "My Widget",
4
moduleName -> thisModel().name,
5
reportWidget -> new ReportWidget (designPath -> "Reports/MyWidget/myReport.jrxml"),
6
parametersForm -> {reportFrame:ReportFrame -> new MyWidget(reportFrame)},
7
defaultParameters -> [->],
8
width -> 3,
9
height -> null
10
),
11
...
2.17.2.2
Adding a Custom Widget with a Form
To add a custom widget that will display a Form definition as its content, do the following:
1. In the Reports folder of your bam module, create a folder for your widget.
Alternatively you can create the widget resources in a separate Module and import the Module into the bam
Module.
2. In the folder, create the form definition that will be used as the content of the widget.
3. Set the supertype of the form to bamLibrary::FormContent.
246
Modeling
4. Add the widget to the Bam document:
(a) In GO-BPMN Explorer, select the bam.docs definition.
(b) In the document editor, select BamDocument.
(c) In the UI definition property, add the WidgetDefinition with the content of the form widget: form←-
Widget -> new FormWidget(reportForm -> { widgetData:WidgetData ->
new <MYFORM>()})
1 new WidgetDefinition(
2
name -> #"Simple Widget with a Form",
3
moduleName -> thisModel().name,
4
formWidget -> new FormWidget(reportForm -> { widgetData:WidgetData -> new WidgetForm()})
5 )
2.17.2.2.1
Sending Parameters to a Form of a Custom Widget
To define the default parameters and parameter-input form for a widget with a form, do the following:
1. Define your default parameters of the WidgetDefinition as a map and make the form take the default values
of widget parameters. Alternatively, pass the WidgetData object as its input parameter: the object holds the
parameter values for the widget.
1 new WidgetDefinition(
2
name -> #"Simple Widget with a Form",
3
moduleName -> thisModel().name,
4
defaultParameters -> ["widgetParameter" -> "default param"],
5
formWidget -> new FormWidget(reportForm -> { widgetData:WidgetData -> new
EkoForm(defaultParameterValue))})
6 )
(a) Create a parametric constructor with the parameters and set them as value on the respective components
1 public EkoForm(String defaultParameterValue){
2
label.setValue(defaultParameterValue);
3 }
(b) Implement the refresh() method on the form that will refresh any components that depend on the
parameters.
1 public void refresh(WidgetDefinition widgetDefinition, WidgetData widgetData, Popup parametersPopup){
2
this.widgetData := widgetData;
3
if label != null then
4
label.refresh();
5
end
6
}
2.17 Monitoring
247
2. Create the form for parameter setting:
(a) Design the parameter form with input components for parameters.
(b) Create a local variable of type ReportFrame: the variable will hold the ReportFrame object passed from
the WidgetDefinition object.
(c) Create a parametric constructor with a ReportFrame argument and store it in a local variable.
1 public ParameterInputForm(ReportFrame rf){
2
reportFrame := rf;
3 }
The ReportFrame will serve to apply parameter values in the widget. Hence make sure that the parameter values are reflected back in the parameters map of the ReportFrame.
1 reportFrame.widgetData.parameters := ["widgetParameter" -> myParameterValue]
(d) Add the refresh() call on the report frame from your form to apply the parameter values and close
the popup with the parameter form.
(e) In the UIDefinition property of the bam Document, define the parametersForm property of your Widget←Definition: note that this is a closure with the ReportFrame of the WidgetDefinition as its input argument.
Create the parameter form with the report frame as its parameter. (The report frame holds all the data
for your widget instance).
1 new WidgetDefinition(
2
name -> #"Simple Widget with a Form",
3
moduleName -> thisModel().name,
4
parametersForm -> {reportFrame:ReportFrame -> new ParameterForm(reportFrame)},
5
defaultParameters -> ["widgetParameter" -> "default param"],
6
formWidget -> new FormWidget(reportForm -> { widgetData:WidgetData -> new EkoForm(widgetData)})
7 )
2.17.3
Creating Business Activity Monitor from Scratch
To create a Business Activity Monitor from scratch only using the bamLibrary Module, first you will need to implement
the widgets and then create a document with the Bam application:
1. Import the bamLibrary Module into your Module (Right-click Module > Module Imports; in the dialog box,
click Add and double-click bamLibrary).
2. Create the widgets:
(a) Copy the JasperReports for your widgets into the Module.
(b) Create the parameter form that will allow you to change the parameters of the report:
i. Create a Form definition.
ii. Insert components that will allow the user to define new parameter values. Make sure to define IDs
on the component so you can acquire their values when setting new report values in the get←Parameter() method later.
iii. Create a local form variable of the type ReportFrame: the ReportFrame object will allow passing of
parameters from the form to the report.
iv. Declare the constructor of the Form that will take the ReportFrame object as its member variable.
public MyParamForm(ReportFrame reportFrame) {this.reportFrame :=
reportFrame}
v. Create the getParameter() method for the parameter form: it must return a Map of the parameters and their new values.
1 public Map<String, Object> getParameters(){
2
def String newParameterValue := MyParamInput.getValue();
3
[ "myParam" -> newParameterValue ]
4 }
(c) Create a component, such as a Button, that will send the new parameters to the ReportFrame and
refresh the report:
i. In the parameter form, insert a component that will send the data.
248
Modeling
ii. Define the send logic and refresh of the report, for example, you can create a Button with a Click
Listener:
1 { e ->
2
if reportFrame == null then
3
Forms.navigateToUrl(embeddedJasperReportUrl(thisModel().name,
4
"myReport.jrxml", getParameters()))
5
else
6
//set the new report parameters from the ReportFrame:
7
reportFrame.setParameters(getParameters());
8
//Display the report:
9
reportFrame.refresh()
10
end
11 }
Figure 2.180 Parameter widget definition with the ReportFrame local variable and added methods
highlighted; also not the Apply button Click expression in the Properties view
3. Create the BAM application:
(a) Create a document: this will be your BAM document.
(b) Define the properties of the Document and define the UI definition as the BamApplicationForm()
with a BamConfiguration as its parameter.
• BamConfiguration holds a list of WidgetDefinitions of widgets available for the Dashboards of the
BamApplicationForm;
• WidgetDefinitions define the available Widgets and their properties:
– name: name of the Widget
– module name: name of the parent Module
– designPath: path to your report relative to the module
– parametersForms: form that is used to collect parameters for the report via ReportFrame (if
undefined, no param settings available)
– defaultParameters - default parameters for the report
– width: default width of the widget
– height: default height of the widget
1 new BamApplicationForm(new BamConfiguration(
2
widgets -> [
3
new WidgetDefinition(
2.17 Monitoring
4
5
6
7
8
9
10
11
12
]
13 ))
249
name -> "My BAM Dashboard Widget",
moduleName -> thisModel().name,
//We pass the ReportFrame with data about the Widget to the parameter form:
parametersForm -> { reportFrame:ReportFrame -> new MyParameterForm(reportFrame)},
defaultParameters -> [ "myWidgetParam" -> "Default parameter value for my report."],
designPath -> "myJasperReport.jrxml",
width -> 4,
height -> 4)
You can now deploy the Module with your custom BAM to the LSPS Server.
2.17.4
Configuring the Data Source for Reports
By default, reports use data from the LSPS_DS data source. To use data from another data source, do the
following:
1. Create the data source to your database on your server with LSPS: refer to the documentation of your application server.
Example datasource configuration on WildFly
1 <xa-datasource jndi-name="java:/jdbc/REPORT_DS" pool-name="REPORT_DS" enabled="true"
use-java-context="false">
2
<xa-datasource-property name="URL">
3
jdbc:h2:tcp://localhost/h2/reports;MVCC=TRUE;LOCK_TIMEOUT=60000
4
</xa-datasource-property>
5
<driver>h2</driver>
6
<transaction-isolation>TRANSACTION_READ_COMMITTED</transaction-isolation>
7
<xa-pool>
8
<min-pool-size>10</min-pool-size>
9
<max-pool-size>20</max-pool-size>
10
<prefill>true</prefill>
11
</xa-pool>
12
<security>
13
<user-name>lsps</user-name>
14
<password>lsps</password>
15
</security>
16 </xa-datasource>
2. In your reports, set the report property com.whitestein.lsps.monitoring.datasource-jndi-name
to the data source, in the example above, REPORT_DS:
(a) In Jasper Studio, open your report.
(b) In the report Outline view, click the root component.
(c) In the Properties view of the root component, click the Advanced tab.
(d) Under the Misc node next to the Properties item, click ....
(e) In the popup, enter the property name com.whitestein.lsps.monitoring.datasource-jndi-name
and the value with the JNDI name of the data source, in the example, java:/jdbc/REPORT_DS.
3. Design your report.
2.17.5
Working with the Front End
2.17.5.1
Creating Dashboards
Dashboards are spaces that display widgets with Jasper Reports. By default, a dashboard belongs to the user who
created the dashboards and cannot be accessed by other users unless the dashboard is marked as public.
To create a new dashboard, do the following:
1. Click Add dashboard.
2. In the dialog on the New dashboard tab, define the dashboard name.
3. Select the Public checkbox if applicable.
4. Click Add.
The dashboard appears in the list of dashboards above the Add dashboard button.
250
2.17.5.1.1
Modeling
Publishing and Unpublishing Dashboards
To change the setting of the public flag on your Dashboard, click the respective button in the Dashboard caption.
Figure 2.181 Publishing a private dashboard
2.17.5.1.1.1
Adding Public Dashboards
To add a public dashboard created by another user to your BAM, do the following:
1. Click the Add dashboard button.
2. In the popup, select the Public dashboard tab and select the dashboard in the combo box.
3. Click Add to confirm.
The public dashboard appears in the list of dashboards above the Add dashboard button. Note that public dashboards created by other users are read only.
2.17 Monitoring
251
Figure 2.182 Adding a public dashboard
2.17.5.1.2
Copying Dashboard
Since the user can edit only the dashboard they created, it is convenient to be able to copy dashboards.
To create a copy of a dashboard, click the Copy button in the caption of the dashboard.
Figure 2.183 Copying dashboard
2.17.5.1.3
Renaming Dashboards
To change the caption of your dashboard, click the Rename button (
Note that you cannot edit public dashboards.
) in the dashboard caption.
252
Modeling
2.17.5.1.4
Deleting Dashboards
To delete a dashboard, do one of the following:
• Right-click the dashboard button in the Business Activity Monitor document and click Remove in the context
menu.
• Click the Delete button in the dashboard caption.
Note: When you delete a public dashboard, the dashboard will no longer be available to any users.
2.17.5.2
Displaying Widgets
BAM widgets are components with Jasper Reports that are displayed on a dashboard. Widgets can take parameters
that are then used by the Jasper Reports.
To display a widget on a dashboard, do the following:
1. Open the dashboard.
2. In the caption of the dashboard, click the Add (+) button in the caption of the dashboard.
3. In the dialog box, select the widget and click Add widget.
On your dashboards, you can drag-and-drop the widgets and resize them as required. On public dashboards, the
positions and dimensions are fixed.
2.17 Monitoring
253
Figure 2.184 Dragging a widget
2.17.5.2.1
Changing Widget Parameters
To change parameters used by a widget, click the Settings button in the widget caption and set the parameters in
the popup box. If the report does not require any parameters, the button is not available.
Figure 2.185 Edit parameters button in the widget caption
2.17.5.2.2
Renaming Widgets
To change the caption of a widget displayed on your dashboard, click the Rename button (
caption.
) in the widget
Note that you cannot edit public dashboards.
2.17.5.2.3
Exporting Reports to PDF, Word, or Excel
To export the report displayed in a widget, click the export button
format.
in the caption of the widget and select the target
254
Modeling
2.18
Debugging
The LSPS Debugger manages LSPS breakpoints on elements and expressions in the debugged model instance.
The breakpoints are defined in the model in your PDS workspace and uploaded to the target LSPS Server at the
moment the LSPS debugger is enabled.
Both the JVM and Execution Engine of the target server run in debug mode. To start debugging, you need to enable
it. When enabled the following happens:
1. LSPS Debugger creates Java breakpoints in the Execution Engine that are used to stop the execution on
LSPS breakpoints;
2. Any LSPS breakpoints present on the server are discarded.
3. The LSPS breakpoints defined in PDS are uploaded to the server.
You can use the following views to manage the debugging process:
• Watch Diagram: diagram with the current breakpoint if the breakpoint is on a modeling element
• LSPS Expression: expression with the current breakpoint if the breakpoint is on an expression
• LSPS Variables: variables from the current execution context
This includes modeling elements and their properties, variables, etc.
• LSPS Watch Expressions: expressions which are evaluated as the model is debugged
2.18.1
Debugger Implementation
When a model instance is running in an Execution Engine in debug mode (the underlying JVM is running in debug
mode and its Execution Engine runs in debug mode), the engine notifies the LSPS Debugger when it hits an
execution step marked by an LSPS breakpoint (you can add LSPS breakpoints to an execution step in the Modeling
perspective).
The LSPS Debugger evaluates the breakpoint condition and if the condition evaluates to true, it notifies the Java
Debugger to suspend the execution in the execution step. An execution step is any of the following:
• Sending a token to a process element
• Changing of goal status
• Interpreting an expression
• Assigning a value to a variable
• Assigning a value to a Record property
• Creating a record instance
2.18 Debugging
255
Figure 2.186 LSPS debugger implementation
Note the LSPS Debugger requires Java breakpoints in the correct spot to suspend the underlying Java execution.
These breakpoints are created when you enable the LSPS debugger and are visible in the Breakpoints view, while
LSPS breakpoints are displayed in the dedicated LSPS Breakpoints view. If you remove these Java breakpoints,
the LSPS debugging will be disabled.
2.18.2
Debugger Connection
You can connect the LSPS Debugger and debug a model instance that runs on an Execution Engine in a local JVM
or on a remote JVM as follows:
• To debug locally, run the PDS Embedded Server in debug mode (refer to Debugging on the PDS Embedded
Server). If you want to debug your custom Process Application, adjust the launcher to the debug mode.
• To debug remotely on the LSPS Cloud server, establish the debug connection (refer to Debugging on the
Cloud Server).
• To debug remotely, connect to an Execution Engine with the model instance (refer to Debugging on a Remote
Server).
Generally, connection of LSPS Debugger to a server, remote or local, is defined in a debug configuration. However,
the connection to the PDS Embedded Server is integrated in PDS and it is sufficient to modify the server properties,
so it runs in debug mode.
256
Modeling
Figure 2.187 Debugger schema
2.18.2.1
Debugging on the PDS Embedded Server
When debugging on the PDS Embedded Server, PDS connects to the server as to a remote server.
To run the PDS Embedded Server in debug mode, you need to pass the server the required debug parameters and
create a remote connection:
1. Go to Server Connections -> Server Connection Settings, select LSPS Embedded Server and click Edit.
2. In the VM Arguments field, add argument that will run the JVM and the Execution Engine in debug mode:
-agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=4000 -←DlspsDebug=true
The -DlspsDebug=true argument runs the Execution Engine in debug mode.
2.18 Debugging
257
Figure 2.188 Debug parameters in the PDS Embedded Server configuration
Important: Make sure the user used to establish the connection has the security right for
debugging: go to the Person view of the Management perspective and check that at least one
security role of the person has the Debugger:Manage permission.
3. Click OK in the error notification dialog.
4. Start the Embedded Server.
5. Create a debug configuration:
(a) Switch to the Debug perspective.
(b) Go to Run > Debug Configurations > Remote Java Application.
(c) Click the New button in the New button and on the right define the details of the server:
• Set the host to localhost and port to 4000.
• Enter a Java project name into the Project field (create an empty Java project if necessary).
258
Modeling
Figure 2.189 Setting debug configuration
(d) Run the debug configuration to attach the LSPS Debugger to the server.
6. Enable debugging: click the Debug button in the LSPS Breakpoints.
Now you can debug the model: add breakpoints to the model and run the model.
Important: If your breakpoints are on expressions or code, not visual modelling elements, the debugger might be stuck before reaching the breakpoint: in such a case, double click the first method in the
current thread to refresh the views.
2.18.2.2
Debugging on the Cloud Server
Note: Make sure you are working with the PDS Cloud Edition.
To debug on the LSPS Cloud server, do the following:
1. Create an empty Java project in your workspace.
2. Switch to the Debug perspective.
3. Go to Run > Debug Configurations.
4. In the Debug Configurations dialog, create a new Remove Java Application configuration.
2.18 Debugging
259
5. Set the configuration settings as follows:
• Project: name of the empty Java project
• Connection type: LSPS Cloud (Socket Attach)
• Host: name of your cloud server
• Port: 8787
Figure 2.190 Debug connection to a cloud server
6. Debug your models as instructed in Debugging Model Instances.
2.18.2.3
Debugging Custom Process Application Locally
Important: Make sure that you run and connect to the server in debug mode from the same PDS.
To debug your Custom Process Application locally, do the following:
1. Open the Java perspective.
2. Go to Run > Debug Configurations > Java Application > <YOUR_APP_LAUNCHER> (for example, My←CustomApp Embedded Server Launcher).
260
Modeling
3. Edit the configuration: add the -DlspsDebug=true VM argument.
Figure 2.191 Setting application launcher configuration to debug mode
4. Run the launcher configuration in debug.
2.18 Debugging
261
Figure 2.192 Running the launcher in debug
5. Enable debugging: go to the Debug perspective and click the Debug button in the LSPS Breakpoints.
Figure 2.193 The LSPS debug is enabled: the Java breakpoints are in place.
Now you can debug the model: add breakpoints to the model and run the model.
2.18.2.4
Debugging on a Remote Server
Important: Only one user can connect to the Execution Engine in debug mode since, on connection
establishing, any LSPS breakpoints on the server are discarded. If you need to prevent such a scenario,
restrict access of users to the debug feature (unassign any security roles with the Debugger security
right).
262
Modeling
To set up LSPS debugging, do the following:
1. Make sure the server with the LSPS Execution Engine runs in debug mode with the VM arguments:
1 -agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=4000 -DlspsDebug=true
2. Open the Debug perspective.
3. Create an empty Java project in your workspace.
4. Go to Run > Debug Configurations > Remote Java Application.
5. Click the New button in the New button and on the right define the details of the remote server.
Figure 2.194 Setting connection to a remote server
6. Run the debug configuration to attach the LSPS Debugger to the server.
7. To start debugging, go to the Debug perspective and click the Debug button in the LSPS Breakpoints to
enable the debugging.
When debugging is enabled, the following takes place:
(a) LSPS Debugger creates a Java breakpoint in the Execution Engine that are used to stop the execution
on LSPS breakpoints;
(b) Any LSPS breakpoints present on the server are discarded.
2.18 Debugging
263
(c) PDS uploads all LSPS breakpoints to the server.
Figure 2.195 The LSPS debug is enabled: the Java breakpoints are in place.
Now you can debug the model instances of your model: add breakpoints to the model and step through
the execution in the LSPS Expression window of the Debug perspective.
2.18.3
Debugging Model Instances
Once you have established connection to the LSPS debugger and enabled debugging, you can start debugging
your model instance:
1. Switch to the Debug perspective.
2. Make sure the Debug view contains, the server threads and the Breakpoints view the DebuggerImpl breakpoints.
Figure 2.196 Local Embedded server in debug mode and debug enabled
3. Switch to the Modeling perspective:
264
Modeling
(a) Add breakpoints to the module resources.
(b) Run the Model.
4. Switch to the Debug perspective.
5. If the views do not contain the correct data, double-click the first method in the current thread to refresh the
views.
Figure 2.197 Caption text
6. Manage the debug execution with the buttons in the LSPS Expression view toolbar.
When the model instance hits a breakpoint, the Java thread of the Execution Engine is suspended. Note that the
model instance state remains unchanged.
2.18.3.1
Adding and Removing Breakpoints
Before you can debug a model instance running in the Execution Engine in debug mode, you need to import the
underlying model into the workspace.
To add or remove a breakpoint to an element, do the following:
1. In the Modeling perspective, open the resource with the respective element, such as, variable definition or an
expression.
2. Right-click the element and click Add Breakpoint or Remove Breakpoint.
• You can add breakpoints to the following:
– expressions: right-click the expression and select Add Breakpoint from the context menu. >
Important: In the following cases, breakpoints are ignored: > ∗ Breakpoints on method or function
signatures are ignored (add a breakpoint to the first expression in their bodies).
2.18 Debugging
265
– BPMN modeling elements: right-click the element on the canvas and select Add Breakpoint from
the context menu.
– Goals: right-click the element on the canvas and select Add Breakpoint from the context menu.
– variables: right-click the variable definition and select Add Breakpoint from the context menu.
– records or their properties: in the Outline view, right-click the record or its property and select Add
Breakpoint from the context menu.
Note: Breakpoints on method or function signatures are ignored: if you need to stop at the function or
method start, add a breakpoint to the first expression in its body.
An added breakpoint appears in the LSPS Breakpoints view in the Debug perspective and is displayed as a dot
marker in the diagram.
When the breakpoint is triggered, it is visualized either in the Watch Diagram or in the LSPS Expression view,
depending on the breakpoint type.
Figure 2.198 Active breakpoint in a Goal hierarchy
2.18.3.2
Defining a Breakpoint Condition
If a breakpoint defines a condition, it is activated only if the condition evaluates to true when the breakpoint is hit.
To add a condition to a breakpoint, select the breakpoint in the LSPS Breakpoints view and define the condition in
the Condition area below.
Important: It is not possible to define a breakpoint on a loop with a condition so as to have the
breakpoint activated at a certain iteration.
266
2.18.3.3
Modeling
Resuming Breakpoints
To resume a model instance to the next breakpoint, click the respective button, such as Resume, Step Over, etc., in
the LSPS Expressions view.
2.18.3.4
Enabling and Disabling Breakpoints
You can disable and enable LSPS breakpoints as well as define breakpoint conditions in the LSPS Breakpoints
view.
2.19
Profiling
Profiling serves to identify possible performance problems in execution of expressions, such as, function calls,
assignment, multi-instance calls, etc. It creates a list of function calls that take more than 0.1 ms to execute with
statics on their duration and their invocation count. The list contains all relevant calls for the time period when the
server was running in profiling mode.
2.19.1
Enabling Profiling
To enable profiling, run your server with the property -DlspsProfile=true.
For your Embedded server, you can do so as follows:
1. Stop the Embedded server.
2. Go to Server Connections -> Server Connection Settings
3. In the Preferences dialog under Process Design Suite -> Management -> Server Connections edit the
LSPS Embedded Server connection.
2.19 Profiling
267
Figure 2.199 Profiler-enabling property on the Embedded Server connection setting
2.19.2
Performing Model Profiling
To profile a model, do the following:
1. Make sure you are connected to a running server with the profiler enabled.
2. In the Management perspective, open the Profiler view.
3. Run the models you want to profile.
Note that if other users are running models on the server, their model instances will be included in the profiler
results.
4. Refresh the Profiler view to display the profiling results. You can click the calls to display it in the Module if it
is available in the Workspace.
268
Modeling
Figure 2.200 Profiler view with results
Note that the queue with the function statistics contains only the most recent function calls. To display the most
expensive function calls of the profiling sessions, click the Expensive Operations
2.19.3
Importing and Exporting Profiling Results
To import or export profiling results in XML, click the export
view.
2.20
button in the view toolbar.
button or the import
button in the Profiler
Debugging
The LSPS Debugger manages LSPS breakpoints on elements and expressions in the debugged model instance.
The breakpoints are defined in the model in your PDS workspace and uploaded to the target LSPS Server at the
moment the LSPS debugger is enabled.
Both the JVM and Execution Engine of the target server run in debug mode. To start debugging, you need to enable
it. When enabled the following happens:
1. LSPS Debugger creates Java breakpoints in the Execution Engine that are used to stop the execution on
LSPS breakpoints;
2. Any LSPS breakpoints present on the server are discarded.
3. The LSPS breakpoints defined in PDS are uploaded to the server.
You can use the following views to manage the debugging process:
• Watch Diagram: diagram with the current breakpoint if the breakpoint is on a modeling element
• LSPS Expression: expression with the current breakpoint if the breakpoint is on an expression
• LSPS Variables: variables from the current execution context
This includes modeling elements and their properties, variables, etc.
• LSPS Watch Expressions: expressions which are evaluated as the model is debugged
2.20 Debugging
2.20.1
269
Debugger Implementation
When a model instance is running in an Execution Engine in debug mode (the underlying JVM is running in debug
mode and its Execution Engine runs in debug mode), the engine notifies the LSPS Debugger when it hits an
execution step marked by an LSPS breakpoint (you can add LSPS breakpoints to an execution step in the Modeling
perspective).
The LSPS Debugger evaluates the breakpoint condition and if the condition evaluates to true, it notifies the Java
Debugger to suspend the execution in the execution step. An execution step is any of the following:
• Sending a token to a process element
• Changing of goal status
• Interpreting an expression
• Assigning a value to a variable
• Assigning a value to a Record property
• Creating a record instance
Figure 2.201 LSPS debugger implementation
Note the LSPS Debugger requires Java breakpoints in the correct spot to suspend the underlying Java execution.
These breakpoints are created when you enable the LSPS debugger and are visible in the Breakpoints view, while
LSPS breakpoints are displayed in the dedicated LSPS Breakpoints view. If you remove these Java breakpoints,
the LSPS debugging will be disabled.
2.20.2
Debugger Connection
You can connect the LSPS Debugger and debug a model instance that runs on an Execution Engine in a local JVM
or on a remote JVM as follows:
• To debug locally, run the PDS Embedded Server in debug mode (refer to Debugging on the PDS Embedded
Server). If you want to debug your custom Process Application, adjust the launcher to the debug mode.
• To debug remotely on the LSPS Cloud server, establish the debug connection (refer to Debugging on the
Cloud Server).
270
Modeling
• To debug remotely, connect to an Execution Engine with the model instance (refer to Debugging on a Remote
Server).
Generally, connection of LSPS Debugger to a server, remote or local, is defined in a debug configuration. However,
the connection to the PDS Embedded Server is integrated in PDS and it is sufficient to modify the server properties,
so it runs in debug mode.
Figure 2.202 Debugger schema
2.20.2.1
Debugging on the PDS Embedded Server
When debugging on the PDS Embedded Server, PDS connects to the server as to a remote server.
To run the PDS Embedded Server in debug mode, you need to pass the server the required debug parameters and
create a remote connection:
1. Go to Server Connections -> Server Connection Settings, select LSPS Embedded Server and click Edit.
2. In the VM Arguments field, add argument that will run the JVM and the Execution Engine in debug mode:
-agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=4000 -←DlspsDebug=true
The -DlspsDebug=true argument runs the Execution Engine in debug mode.
2.20 Debugging
271
Figure 2.203 Debug parameters in the PDS Embedded Server configuration
Important: Make sure the user used to establish the connection has the security right for
debugging: go to the Person view of the Management perspective and check that at least one
security role of the person has the Debugger:Manage permission.
3. Click OK in the error notification dialog.
4. Start the Embedded Server.
5. Create a debug configuration:
(a) Switch to the Debug perspective.
(b) Go to Run > Debug Configurations > Remote Java Application.
(c) Click the New button in the New button and on the right define the details of the server:
• Set the host to localhost and port to 4000.
• Enter a Java project name into the Project field (create an empty Java project if necessary).
272
Modeling
Figure 2.204 Setting debug configuration
(d) Run the debug configuration to attach the LSPS Debugger to the server.
6. Enable debugging: click the Debug button in the LSPS Breakpoints.
Now you can debug the model: add breakpoints to the model and run the model.
Important: If your breakpoints are on expressions or code, not visual modelling elements, the debugger might be stuck before reaching the breakpoint: in such a case, double click the first method in the
current thread to refresh the views.
2.20.2.2
Debugging on the Cloud Server
Note: Make sure you are working with the PDS Cloud Edition.
To debug on the LSPS Cloud server, do the following:
1. Create an empty Java project in your workspace.
2. Switch to the Debug perspective.
3. Go to Run > Debug Configurations.
4. In the Debug Configurations dialog, create a new Remove Java Application configuration.
2.20 Debugging
273
5. Set the configuration settings as follows:
• Project: name of the empty Java project
• Connection type: LSPS Cloud (Socket Attach)
• Host: name of your cloud server
• Port: 8787
Figure 2.205 Debug connection to a cloud server
6. Debug your models as instructed in Debugging Model Instances.
2.20.2.3
Debugging Custom Process Application Locally
Important: Make sure that you run and connect to the server in debug mode from the same PDS.
To debug your Custom Process Application locally, do the following:
1. Open the Java perspective.
2. Go to Run > Debug Configurations > Java Application > <YOUR_APP_LAUNCHER> (for example, My←CustomApp Embedded Server Launcher).
274
Modeling
3. Edit the configuration: add the -DlspsDebug=true VM argument.
Figure 2.206 Setting application launcher configuration to debug mode
4. Run the launcher configuration in debug.
2.20 Debugging
275
Figure 2.207 Running the launcher in debug
5. Enable debugging: go to the Debug perspective and click the Debug button in the LSPS Breakpoints.
Figure 2.208 The LSPS debug is enabled: the Java breakpoints are in place.
Now you can debug the model: add breakpoints to the model and run the model.
2.20.2.4
Debugging on a Remote Server
Important: Only one user can connect to the Execution Engine in debug mode since, on connection
establishing, any LSPS breakpoints on the server are discarded. If you need to prevent such a scenario,
restrict access of users to the debug feature (unassign any security roles with the Debugger security
right).
276
Modeling
To set up LSPS debugging, do the following:
1. Make sure the server with the LSPS Execution Engine runs in debug mode with the VM arguments:
1 -agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=4000 -DlspsDebug=true
2. Open the Debug perspective.
3. Create an empty Java project in your workspace.
4. Go to Run > Debug Configurations > Remote Java Application.
5. Click the New button in the New button and on the right define the details of the remote server.
Figure 2.209 Setting connection to a remote server
6. Run the debug configuration to attach the LSPS Debugger to the server.
7. To start debugging, go to the Debug perspective and click the Debug button in the LSPS Breakpoints to
enable the debugging.
When debugging is enabled, the following takes place:
(a) LSPS Debugger creates a Java breakpoint in the Execution Engine that are used to stop the execution
on LSPS breakpoints;
(b) Any LSPS breakpoints present on the server are discarded.
2.20 Debugging
277
(c) PDS uploads all LSPS breakpoints to the server.
Figure 2.210 The LSPS debug is enabled: the Java breakpoints are in place.
Now you can debug the model instances of your model: add breakpoints to the model and step through
the execution in the LSPS Expression window of the Debug perspective.
2.20.3
Debugging Model Instances
Once you have established connection to the LSPS debugger and enabled debugging, you can start debugging
your model instance:
1. Switch to the Debug perspective.
2. Make sure the Debug view contains, the server threads and the Breakpoints view the DebuggerImpl breakpoints.
Figure 2.211 Local Embedded server in debug mode and debug enabled
3. Switch to the Modeling perspective:
278
Modeling
(a) Add breakpoints to the module resources.
(b) Run the Model.
4. Switch to the Debug perspective.
5. If the views do not contain the correct data, double-click the first method in the current thread to refresh the
views.
Figure 2.212 Caption text
6. Manage the debug execution with the buttons in the LSPS Expression view toolbar.
When the model instance hits a breakpoint, the Java thread of the Execution Engine is suspended. Note that the
model instance state remains unchanged.
2.20.3.1
Adding and Removing Breakpoints
Before you can debug a model instance running in the Execution Engine in debug mode, you need to import the
underlying model into the workspace.
To add or remove a breakpoint to an element, do the following:
1. In the Modeling perspective, open the resource with the respective element, such as, variable definition or an
expression.
2. Right-click the element and click Add Breakpoint or Remove Breakpoint.
• You can add breakpoints to the following:
– expressions: right-click the expression and select Add Breakpoint from the context menu. >
Important: In the following cases, breakpoints are ignored: > ∗ Breakpoints on method or function
signatures are ignored (add a breakpoint to the first expression in their bodies).
2.20 Debugging
279
– BPMN modeling elements: right-click the element on the canvas and select Add Breakpoint from
the context menu.
– Goals: right-click the element on the canvas and select Add Breakpoint from the context menu.
– variables: right-click the variable definition and select Add Breakpoint from the context menu.
– records or their properties: in the Outline view, right-click the record or its property and select Add
Breakpoint from the context menu.
Note: Breakpoints on method or function signatures are ignored: if you need to stop at the function or
method start, add a breakpoint to the first expression in its body.
An added breakpoint appears in the LSPS Breakpoints view in the Debug perspective and is displayed as a dot
marker in the diagram.
When the breakpoint is triggered, it is visualized either in the Watch Diagram or in the LSPS Expression view,
depending on the breakpoint type.
Figure 2.213 Active breakpoint in a Goal hierarchy
2.20.3.2
Defining a Breakpoint Condition
If a breakpoint defines a condition, it is activated only if the condition evaluates to true when the breakpoint is hit.
To add a condition to a breakpoint, select the breakpoint in the LSPS Breakpoints view and define the condition in
the Condition area below.
Important: It is not possible to define a breakpoint on a loop with a condition so as to have the
breakpoint activated at a certain iteration.
280
2.20.3.3
Modeling
Resuming Breakpoints
To resume a model instance to the next breakpoint, click the respective button, such as Resume, Step Over, etc., in
the LSPS Expressions view.
2.20.3.4
Enabling and Disabling Breakpoints
You can disable and enable LSPS breakpoints as well as define breakpoint conditions in the LSPS Breakpoints
view.
2.21
Profiling
Profiling serves to identify possible performance problems in execution of expressions, such as, function calls,
assignment, multi-instance calls, etc. It creates a list of function calls that take more than 0.1 ms to execute with
statics on their duration and their invocation count. The list contains all relevant calls for the time period when the
server was running in profiling mode.
2.21.1
Enabling Profiling
To enable profiling, run your server with the property -DlspsProfile=true.
For your Embedded server, you can do so as follows:
1. Stop the Embedded server.
2. Go to Server Connections -> Server Connection Settings
3. In the Preferences dialog under Process Design Suite -> Management -> Server Connections edit the
LSPS Embedded Server connection.
2.21 Profiling
281
Figure 2.214 Profiler-enabling property on the Embedded Server connection setting
2.21.2
Performing Model Profiling
To profile a model, do the following:
1. Make sure you are connected to a running server with the profiler enabled.
2. In the Management perspective, open the Profiler view.
3. Run the models you want to profile.
Note that if other users are running models on the server, their model instances will be included in the profiler
results.
4. Refresh the Profiler view to display the profiling results. You can click the calls to display it in the Module if it
is available in the Workspace.
282
Modeling
Figure 2.215 Profiler view with results
Note that the queue with the function statistics contains only the most recent function calls. To display the most
expensive function calls of the profiling sessions, click the Expensive Operations
2.21.3
Importing and Exporting Profiling Results
To import or export profiling results in XML, click the export
view.
2.22
button in the view toolbar.
button or the import
button in the Profiler
Resource Sharing
• Exporting of Modules You can export Modules with their resources as a bundle, which is ready to be deployed
to the LSPS Server, as a library, which can be used as a source of elements referenced by other user from
their Modules, as a package that other users can import and work with, or as an XPDL so you can import
your Processes to other BPMN designing tools.
• Export Configuration Export configurations store setting of an export so you do not have to enter common
exports all over again every time.
• Import You can import modules packages exported by another user with PDS, or XPDL files.
• XPDL XPDL is a standard format that serves for interchange of business process definitions. You can create
an XPDL based on a definition in PDS or import an XPDL to your PDS workspace as a Process definition.
• Library Libraries are Modules exported in a special way since they are intended to be used as resources of
elements that users can reference and use in their Modules.
• Files You can work with external files.
2.22 Resource Sharing
2.22.1
283
Model and Module Export
You can export your Modules as follows:
• modules with their content as a package with your model. Such a package can be used to do the following:
– deployment to the server (refer to GO-BPMN Export)
– reuse other project and modules as libraries (refer to Creating a Library)
– sharing with users of PDS (refer to Exporting with General Export)
– sharing with users of other BPMN products (refer to Exporting to XPDL)
• projects and modules (refer to Exporting with General Export)
2.22.1.1
Export Configurations
To speed up export if you need to export the same resources repeatedly, define an Export Configuration file: the file
contains the list of workspace resources so you can use it as input for the export so you do not have to define the
resources you want to export all over again.
Since they are not considered part of the Model, Export configurations can be located anywhere within a GO-BPMN
project, that is, in a project, Module, or a generic folder.
2.22.1.1.1
Defining an Export Configuration
To define an export configuration, do the following:
1. In the GO-BPMN Explorer, double-click the respective export configuration or create a new export configuration.
2. In the Export Configuration Editor, click Add.
3. In the Add Export Configuration Item dialog box, select the GO-BPMN projects, GO-BPMN Modules, and
folders you wand to include in the configuration file.
4. Click OK.
5. Click File -> Save to save the file.
2.22.1.2
Exporting with General Export
A GO-BPMN module/project can be exported to be shared with other users (without using a version control system).
Project and modules exported to archive files are non-deployable (cannot be uploaded to the server).
To export a GO-BPMN module to an archive file or file system:
1. In the GO-BPMN Explorer view, right-click the GO-BPMN project or module.
2. In the context menu, open Export.
3. In the Export menu select:
• Archive File to export the project/modules to an archive file.
• File System to export the project/modules into a folder structure.
284
Modeling
4. On the File System/Archive file page in the Export dialog box,
(a) select the checkboxes of the projects and modules you want to
(b) include in the file system/archive file. To specify module or project content that you want to include in
the export, click the module or project in the left pane to display its content and in the right pane, select
or unselect the respective resources.
Figure 2.216 Selecting resources and files to be exported into an archive
2.22 Resource Sharing
285
Figure 2.217 Selecting resources and files to be exported into a file system
5. In the Destination file text box, specify the path (and the archive name of the file, for example,
archive.zip). You may click Browse to specify the path.
6. Under Options, specify, if you wish to create directory structure within the archive or create only the selected
directories.
• For archive file select its format (zip or tar), choose, and if you wish to compress the file contents.
• For a file system define if you wish to overwrite existing files without warning.
7. Click Finish.
The archive file or file system is saved in the defined location (refer to http://help.eclipse.org/).
2.22.1.3
Exporting with GO-BPMN Export
The GO-BPMN Export feature allows you to create zip files with a Module, which can be deployed to the server:
the output file contains the Module with all its dependencies. You can perform the export from PDS manually or you
can use the ModelExporter tool available in the maven repo.
Important: If you are exporting Models intended for execution, make sure the respective Module is
flagged as executable in its Properties (in GO-BPMN Explorer, an executable Module is indicated by a
red arrow).
To create a deployable zip file, do the following:
286
Modeling
1. Go to File > Export.
Alternatively right-click the project or module in GO-BPMN Explorer and select Export.
2. In the Export dialog box, expand Process Design Suite and select GO-BPMN Export.
Figure 2.218 Selecting the GO-BPMN Export
3. Click Next.
4. In the GO-BPMN Export dialog box, do the applicable:
• Under GO-BPMN Modules, select the modules to be exported.
• Under Export Configuration, select the desired export configurations.
Modules selected in the GO-BPMN Modules area are exported along with the resources specified in the
selected export configuration (resources are summed up).
2.22 Resource Sharing
287
Figure 2.219 Selecting modules to be exported
5. In the Destination file text box, specify the path and the name file.
> Note: Export name has to include the .zip extension.
6. Click Next and check the list of modules.
7. Click Finish.
The zip file saved in the location specified in the Destination file text box and is ready to be uploaded to the server.
Note: The GO-BPMN export feature drops the project structuring – only modules are preserved.
2.22.1.4
Exporting a Module with Maven
To integrate exporting into your Maven build use ModelExporter available in the LSPS maven repository: Model←Exporter exports a Module with all its dependencies including the Standard Library Modules as a deployable ZIP
file.
To integrate the export in your Maven build include the plug-in in your pom.xml:
288
Modeling
1 <plugin>
2
<groupId>org.codehaus.mojo</groupId>
3
<artifactId>exec-maven-plugin</artifactId>
4
<version>1.2.1</version>
5
<executions>
6
<execution>
7
<goals>
8
<goal>java</goal>
9
</goals>
10
</execution>
11
</executions>
12
<configuration>
13
<mainClass>com.whitestein.lsps.export.ModelExporter</mainClass>
14
<arguments>
15
<argument>d:\CustomerModule</argument>
16
<argument>processes\Main</argument>
17
<argument>d:\CustomerProject\target\stdlib</argument>
18
<argument>d:\result.zip</argument>
19
</arguments>
20
</configuration>
21 </plugin>
Your can then use the resulting zip file as input for the uploadModel in your pom.xml:
1 <plugin>
2
<groupId>org.codehaus.mojo</groupId>
3
<artifactId>exec-maven-plugin</artifactId>
4
<version>1.2.1</version>
5
<executions>
6
<execution>
7
<id>uploadModel</id>
8
<goals>
9
<goal>java</goal>
10
</goals>
11
<phase>deploy</phase>
12
<configuration>
13
<mainClass>com.whitestein.lsps.mconsolecl.Main</mainClass>
14
<arguments>
15
<argument>modelUpload</argument>
16
<argument>-h</argument>
17
<argument>${modelUpload.host}</argument>
18
<argument>-u</argument>
19
<argument>${modelUpload.user}</argument>
20
<argument>-p</argument>
21
<argument>${modelUpload.password}</argument>
22
23
<argument>-m</argument>
24
<argument>d:\result.zip</argument>
25
<argument>--dbUpdateStrategy</argument>
26
<argument>${modelUpload.dbUpdateStrategy}</argument>
27
</arguments>
28
</configuration>
29
</execution>
30
</executions>
31 </plugin>
2.22.2
Import
You can import the following resources into the workspace:
• module packages (archive files) (refer to Importing Model Packages to Workspace)
• XPDL files (refer to Importing XPDL)
• file systems with the project directory structure (refer to Importing File System Location)
You can also import a module that is already in your workspace tree to another module. This module import allows
you to reuse resources, which you have already created in another module (refer to Importing Modules).
2.22 Resource Sharing
2.22.2.1
289
Importing Model Packages to Workspace
If you want to work with external resources, typically with Models that you received from somebody else, you need
to import them into your workspace.
To import a model package to your workspace, do the following:
1. Right-click anywhere inside the GO-BPMN Explorer view and select Import.
Note: If importing a model package created using the GO-BPMN export, make sure a project,
which can accommodate imported modules is created (package contains only modules).
2. In the Import menu box, select Archive File.
3. Click Next.
4. On the Archive file page in the Import dialog box:
(a) In the From archive file text box, type the filepath of the model package.
(b) Click Browse next to the Into folder text box, and in the Import into Folder dialog box, select the project
to import the modules. Click OK.
Figure 2.220 Importing an archive
5. Click Finish.
The model package content is imported to the workspace.
290
Modeling
2.22.2.2
Importing File System Structure
To import a file system structure to the workspace, do the following:
1. Right-click inside the GO-BPMN Explorer view and select Import.
2. In the Import menu, select File System.
To import all GO-BPMN projects contained in a location (including subfolders) select Existing Projects into
Workspace.
3. In the From directory field box, type the path to the file system. Use Browse, if necessary.
4. In the compartment below the From directory field box, select the projects and resources you wish to import.
5. In the Into folder field box, type the path to the project and module to import the file system.
6. Check and select options in the Options area.
7. Click Finish.
The structure appears in the GO-BPMN Explorer tree.
2.22.3
XPDL Resources
XPDL is a standardized format of business models intended for model interchange between different modeling
applications.
You can export your models as XPDL files with the resources supported by the format and you can import such
models to your workspace.
2.22.3.1
Exporting to XPDL
To export your model to an XPDL file, do the following:
1. Go to File > Export.
To export, you can right-click the project or module in GO-BPMN Explorer and select Export.
2. In the Export dialog box, expand Process Design Suite and select XPDL.
3. Click Next.
4. In the XPDL Export dialog box:
• under Module to export, define the module to be exported;
• under XPDL file, define the target file name and path;
• in the Elements to export area, select module elements to be exported;
2.22 Resource Sharing
291
Figure 2.221 Defining XPDL Export settings
5. Click Finish.
2.22.3.2
Importing XPDL
You can import XPDL 2.1 files.
To import an XPDL file to a module, do the following:
1. Right-click anywhere inside the GO-BPMN Explorer view and click Import.
2. In the Import dialog box, expand GO-BPMN Modeler and select XPDL.
3. Click Next.
4. On the next page of the dialog box:
• In the XPDL file text field provide the location of the xpdl file.
• In the Target module provide the target module path (project/module).
• In the Elements to import area, check the elements to import.
5. Click Finish.
292
Modeling
2.22.4
Library
A library is a read-only set of Modules with reusable parts of business models.
Unlike common modules, a library cannot make use of other module or resources as it is intended for heavy reuse
and hence its content should be generic.
Note: Process Design Suite is delivered with a library with generic resources called the Standard
Library. The Standard Library is imported into all GO-BPMN Projects and Modules, which are not able
to function without it.
Related links:
• Resource Sharing
• Importing Modules
Default Libraries
The following libraries are provided out-of-the-box:
• Standard Library: basic resources (refer to the Standard Library Reference Guide or to the documentation in
its modules)
• Exchange Client Library
• Sharepoint Client Library
• Social Library
• Scaffolding Library
• BAM Library
SharePoint and Exchange Client Libraries
Communication with Microsoft SharePoint 2010 and later and Microsoft Exchange 2010 and later is supported by the
SharepointClient and ExchangeClient libraries. The libraries contain web service tasks and supporting resources
(data type resources) to communicate with a Sharepoint and Exchange servers.
The libraries provide only tasks for a subset of the SharePoint and Exchange web services. If necessary, create
your own web service task (refer to Web Service Client).
Note: You can generate an example SharePoint and Exchange projects with BPMN processes and related
resources: To generate the project, go to File > New > Example and select Sharepoint Integration Example or
Exchange Integration Example. Connection details are defined as functions (feel free to use constants instead).
2.22 Resource Sharing
2.22.4.1
293
Importing Library to GO-BPMN Projects
To import a library to a GO-BPMN project:
1. In GO-BPMN Explorer, right-click the respective GO-BPMN project.
2. Click Add Library.
3. In the Add GO-BPMN Library dialog box select:
• Select absolute file path: insert the absolute to the library (absolute path is a complete path to a specific
location).
• Select library variable and the relative path: insert library variable and relative path (variable defines an
absolute path and the relative path defines the path relative to the variable).
• Select a workspace file: insert workspace path to a library zip file available in the workspace.
To remove a library from a GO-BPMN project, in GO-BPMN Explorer, right-click the library and select Remove
(applies also to the Standard Library).
To work with library content, import library modules to the respective module.
2.22.4.2
Exporting Modules as Libraries
To export Modules as a library, do the following:
1. In the GO-BPMN Explorer view, right-click the GO-BPMN project or module.
2. In the context menu, open Export.
3. In the Export menu, select GO-BPMN Library Export.
4. On the Module Selection page of the GO-BPMN Export dialog box, select the checkboxes of the modules you
want to include in the library.
You may apply an export configuration by selecting it in the lower part of the dialog box.
294
Modeling
Figure 2.222 Selecting modules to be exported as a library
5. In the Destination file text box, specify the path (and the archive name of the file, for example,
archive.zip).
6. Click Next to display overview of the added modules modules.
7. Click Finish.
2.22.4.3
Removing Library from a Project
To remove a library from your project, in GO-BPMN Project Explorer, right-click the library reference in your project
and click Remove Library. Note that this removes only the import of the Library, not the Library modules themselves.
2.22.5
Files
2.22.5.1
Loading File
To load files, use the getResource() function.
1 new FileResource({ -> getResource("form_components", "output/myfile.txt")})
2.23
Model Presentation
To present your Models to audience, use the Business Modeling perspective.
Chapter 3
Execution
To be able to execute a Model from PDS, you need to define and establish a connection to an LSPS Server where
you want to run it.
Once you connect PDS to the server, you can upload your Modules directly from your workspace in the Modeling
perspective or you can upload Models exported with GO-BPMN export from the Management perspective.
Once a Model is available on the LSPS Server, you can instantiate it. Typically, you will instantiate Models from the
Management perspective, but PDS allows you to upload and instantiate a Model directly from your workspace to
the server from the Modeling perspective.
Note: You can upload and run your Models also with the Command Line Console as well as from
the Management Console.
You can connect to any LSPS Server; However, by default, PDS provides a connection to its PDS Embedded Server,
which is a WildFly server run locally so you can run your Models and application immediately out-of-the-box. It is
located in the .LSPSEmbedded folder of each workspace. PDS provides a launcher in the main toolbar for quick
access to the server (
).
Important: When you generate the sources of the Default Process Application, the system generates
the SDK Embedded Server with LSPS and its launch configuration. Note that this is another server:
check the referenced libraries of the <APP>-embedded project.
To define the settings of the connection to this server, go to Window > Preferences, and Process Design Suite >
Management > Runtime Connections.
296
Execution
Figure 3.1 Runtime Connection page of the Preferences dialog box with connections to LSPS Servers
3.1
Connecting to the PDS Embedded Server
The PDS Embedded Server is a WildFly server with LSPS running on localhost (typically with the connection URL
http://localhost:8080/lsps-ws). It is delivered as a part of the Process Design Suite and preset as the
default server connection.
You can start and stop the Embedded Server with the Start/Stop Embedded Server button (
toolbar.
and
) in the main
To launch the PDS Embedded Server and connect the Process Design Suite to the server, do the following:
1. Go to Server Connections -> LSPS Embedded Server.
2. Click Start.
Alternatively, click the Start Embedded Server (
) button on the main toolbar.
The server is launched and the Process Design Suite connects to it. You can check the process in the Console
view.
The PDS Embedded Server is located in the .LSPSEmbedded folder in your workspace. If you need to generate
the server again, locate the folder on your file system, remove it, restart the Living Systems® Process Design Suite,
and start the Embedded Server.
3.2 Connecting to an LSPS Server
297
You can check the connection setting of the PDS Embedded Server under Server Connections > Server Connection Settings > LSPS Embedded Server.
Figure 3.2 Runtime Connection page of the Preferences dialog box with connections to LSPS Servers
Note that you can administrate the server with its web console, for example, to change its mail session settings.
Under normal circumstances the console is available on http://localhost:9990/console/
3.2
Connecting to an LSPS Server
To be able to connect to an LSPS Server other than the Embedded Server, you need to define a launch configuration
for the Server:
1. In the menu bar, under LSPS Servers, click Server Connection Settings.
2. In the Server Connections part of the Preferences dialog box, click Add and define the connection settings:
• Server name: arbitrary name of the connection
• Server URL: URL of the server instance to connect to (for example, for the PDS Embedded server
http://localhost:8080/lsps-application)
• User and Password
• Application URL: URL to the LSPS Application on the server
• Database Schema Update Strategy defines how to handle an already existing tables of the data model:
– Do nothing with database schema: data-model tables remain unchanged
If the system detects inconsistencies, the model upload or launching fails.
298
Execution
– Update the schema by model: New tables, columns and relationships are added; no data is
deleted.
– Validate schema first: data-model tables are validated against the new model.
If inconsistencies are detected, the model upload or launching fails.
– Drop/create schema: data-model tables are dropped and recreated.
Note: The Database Schema Update Strategy setting does not tamper with the LSPS
runtime information, such as uploaded models, model instances in the current execution
status, persons details, etc. and the data remains unchanged regardless of the setting.
3. Click Test Connection to make sure the settings are correct.
3.3
Model Upload
When you upload a Model, its Module and all the imported Modules are uploaded to the LSPS Server Model
Repository: each uploaded Module is identified by its name and version. If there is a Module with the same name
and version on the LSPS Server, the Module is replaced.
When uploading a Module from the Modeling Perspective, the target server is by default the Embedded LSPS
Server. To change the target server, go to LSPS Connections > Server Connection Settings and in the dialog
set the default LSPS Server.
3.3.1
Uploading a Module from the Modeling Perspective
When uploading a Module from the Modeling Perspective, the target server is by default the Embedded LSPS
Server.
Note: To change the target server, go to LSPS Connections > Runtime Connection Settings and in
the dialog, set the default LSPS Server. To create a connection to an LSPS Server, refer to Connecting
to an LSPS Server.
Make sure the server is running. To start the LSPS Embedded Server, click the Embedded Server Start (
button.
)
To upload a Model to the default LSPS Server, right-click the Module in GO-BPMN Explorer and in the context
menu, click Upload As > Model.
If you want to upload the Module and create its Model instance immediately, right-click the Module and in the context
menu click Run As > Model.
Note: When uploading a model, a launch configuration is applied. If no launch configuration for a
model is available, a default launch configuration for the model is created.
3.4 Instantiating a Model from the Management Perspective
3.3.2
299
Uploading a Module from the Management Perspective
Check your server connection.
To upload a Model or Modules to the server, do the following:
1. Display the Module Management view (in the toolbar, click the Management Views button (
Module Management).
2. In Module Management view, click the Upload (
) and click
) button.
3. In the Model Upload dialog box define the model details. Every model has to be valid (the system validates it
on upload); otherwise uploading fails.
4. Click OK. The selected Model is uploaded to the current LSPS Server.
5. If you selected the Do not execute schema update scripts flag, the scripts are available in the Schema Update
Scripts tab of the Module Management view. Double click the respective row to have the script displayed.
The Modules on the LSPS Server are listed in the Module Management view.
3.4
Instantiating a Model from the Management Perspective
On Model instantiation, the Execution Engine creates an instance of the Model, which is an executable Module with
all its resources.
Every model instance is assigned a unique ID as many model instances based on the same model may be created.
A model instance may define specific properties in the form of key-value pairs. For more information on Model
instance lifecycle, refer to the GO-BPMN Modeling Language User Guide.
To create a model instance of an uploaded Model, do the following:
1. In the main toolbar, click the arrow in the Management Views (
2. In the toolbar of the displayed Model Instances view, click Create (
) button and select Model Instances.
).
3. In the Model drop-down box of the Model Instance Creation dialog box, choose a model, and click OK.
4. If necessary, in the Properties table, edit the key-value pairs attached to the model instance.
Note: If a Model instance remains in the status Created, check the Error Log for errors.
Figure 3.3 Creating a model instance based on an uploaded executable module
300
3.5
Execution
Instantiating a Model from the Modeling Perspective
To instantiate a Model from the Modeling Perspective, do the following:
1. Right-click the executable Module that represents your Model.
2. In the context menu, go to Run As and select the server configuration. The system uploads the Model to the
LSPS Server defined for the configuration and creates its instance on the server.
3.5.1
Checking Errors
Errors thrown by the Process Design Suite and other environment plug-ins are available in the Error Log view. Each
error entry shows information about the plug-in the error was generated by, and date and time when it occurred.
Double-clicking an error entry opens Event Details dialog box with detailed information on the respective error
message including the date and time of its occurrence, its severity, error message, its stack trace, and session data.
Error Log can contain also entries of the server if these were caused by a Process Design Suite feature, which
appear primarily in the Console view.
Figure 3.4 Error Log view
3.6
Loading and Resetting Database of the LSPS Embedded Server
The content of the LSPS database includes the runtime information, such as uploaded models, model instances in
the current execution status, persons details, etc. Before you reset the database consider exporting it so you can
load it if necessary. When resetting the database, all data is lost.
To save, restore, or reset the LSPS Embedded Server database, do the following:
1. Stop the Embedded Server.
2. Under Server Connections, select LSPS Embedded Server and Database Management.
3. In the Embedded Database Management dialog box:
• Select a database name and click Load to restore a database.
Important: If a database is restored, the current database goes lost.
• Click Save and provide the database name in the displayed dialog box to save the current database.
• Click Reset to erase the database.
Note: The database is stored in the current workspace in the .LSPSEmbedded folder.
3.7 Resetting Database of the Cloud Server
3.7
301
Resetting Database of the Cloud Server
The content of the LSPS database includes the runtime information, such as uploaded models, model instances in
the current execution status, persons details, etc. Note that when resetting the database, all the data gets lost.
To reset the LSPS Cloud Server database, click the Reset Cloud Database
Cloud edition.
icon in the main menu of the PDS
302
Execution
Chapter 4
Model Update
Model update is a mechanism for changing a model used by a model instance on runtime.
A model instance is created based on a model: while the static data is defined by the model, the runtime data exists
in the model instance. Hence, if you want to change the model, you will either let the unfinished model instances
run according to the original model or you will define how they should adapt so they can continue according to the
updated model. You can perform this with the model update feature, which allows you to change the unfinished
model instances so they run according to the new model. The rules for how to adapt the unfinished model instances
is defined in the model update definition file and that including the original and new model, the update pre-condition,
pre-processing processes, transformation rules, and post-processing processes.
On runtime, model update is performed as follows:
1. The model instance is suspended.
2. Pre-condition is evaluated and checked.
The server checks the model-update pre-condition which is a Boolean expression, to decide if a particular
model instance should undergo the model update at all: the model update pre-condition is evaluated in the
context of the original model instance:
• If true, the model update on the model instance starts.
• If false, the model update does not start; the instance remains unchanged, and the event is logged.
3. Model instance is pre-processed.
The elements that were being executed when the model instance was suspended are transformed according
to their pre-processes.
4. The runtime data, that is, records, variables, and relevant asynchronous modeling elements, of the model
instance is transformed so that it follows the new model.
5. Model instance is post-processed.
The post-processes of instantiated elements are executed to prepare them for running.
304
Model Update
Figure 4.1 Schema of Model update process
For examples, on how to update your model and its instances, refer to [Updating a Model]{#ModelUpdateHowTo}.
4.1
Transformation
Transformation is the main phase of model update: The runtime data of the suspended model instance is transformed so the model instance is ready to continue its execution according to the new model.
During the transformation phase, the transformation rules defined in the model update definition are applied on the
relevant model entities. These includes all modified data types, variables, and asynchronous model elements that
were instantiated at the moment the model instance was suspended for model update. Therefore, the user must
define transformation rules for all possibly relevant entities.
For example, if you delete a variable in the new model, the variable is simply removed and no other action is
required. However, if you change the type of a record field on a record, any field values of the record instances must
be transformed accordingly.
Transformation is performed as follows:
• Transformation of modified data types and variables is applied on all instances.
• Transformation defined on asynchronous model elements is applied on the elements that were running before
and will be running after the model update.
Hence, the model update definition must define transformation for the following if they are changed in the new
model:
• data types
Record transformations are defined for record fields of basic data types that have been added or changed
in the new model. The transformation expression returns the value for the new record field instance. The
evaluation is performed for every field instance in the context of the new model instance; however, you can
use the old() function Call to refer to the old data types. As its parameter, the function takes a string
expression that resolves into the name of the record property.
4.1 Transformation
305
Important: It is not possible to transform the type of a Shared Record field since this requires
database migration.
Example: The old() Function Call Syntax
1 old(<STRING_EXPRESSION>)
If a data type has a supertype, it inherits the transformation expression. If it defines its own transformation
expression, the transformation expression of its supertype is not applied.
• variables
Variable transformation expression returns the new variable value. Note that it can be influenced by the transformation on the data types. Therefore, on model update transformation, a modified variable is transformed
according to one of the applicable rules:
– The variable is transformed according to the variable transformation expression.
– If such an expression is not defined, it is transformed according to the data type transformation.
• asynchronous modeling elements that are or will be instantiated
Goals and elements with atomic execution semantics do not define transformation strategy since they cannot
hold a token and can be only deleted or have their parameter values modified while modified asynchronous
elements must define their transformation strategy (refer to Transformation Strategies), since these can become again running when the model instance resumes its execution.
Note: When updating a multi-instance activity, every instance of the activity is treated as a separate
element on update.
Figure 4.2 Schema of transformation
306
Model Update
4.1.1
Transformation Strategies
The transformation strategy specifies how an instantiated asynchronous element that is changed in the new model,
that is, an asynchronous element that was running when the model update was triggered and the model instance
suspended or will be running after the model instance is updated, is treated.
The following model elements must define their transformation strategy if modified in the new model:
• Processes
• Plans
• Activities
The strategy can be set to restart or continue:
• restart: If the element was running when the model update was triggered and will be running after the update,
the context of the element is discarded and is created anew.
• continue: If the element was running when the model update was triggered and will be running after the
update, the context is preserved and the element continues its running with its old context.
Figure 4.3 Transformation strategy semantics
4.2 Model-Update Processes
307
The strategies are applied in a top-down manner: If a task in a sub-process has its strategy set to continue and the
subprocess has its strategy set to restart, the continue strategy of the task will be never applied, since the parent
subprocess will be always restarted if its content is running.
If you deleted an asynchronous model element in the new model and the element was running when model update
was triggered and the model instance suspended, the Start Event of its parent activity becomes running when the
model instance resumes (the token from the deleted element is moved to the closest Start Event). Hence, such
deleted elements do not define the transformation strategy.
Since Goal hierarchies follow a different logic than BPMN-based processes and plan models, they need to be
updated in a way which preserves the status of the Goals and adjusts it if necessary so that the hierarchy is
consistent: Hence, on transformation, the statuses of matched Goals are preserved and the following rules are
applied:
• If a Goal is decomposed in Plans and at least one of the Plans is running, the Goal becomes running.
• If a Goal is inactive and its parent is deactivated, it becomes deactivated as well.
4.2
Model-Update Processes
Model-update processes are BPMN processes that are executed before and after the model-update transformation
phase: They serve as hooks that prepare instantiated elements with a change for transformation and for its running
after the transformation and hence must start with a None Start Event.
Only model-update processes for instantiated elements are executed. that is, for pre-processes, the elements were
in the running stated when the model instance was suspended; for post-processes, they will be in the running state
when the model instance is transformed. If this be a multi-instance activity, every instance of the activity is updated.
You can define model-update processes for Modules, Processes, Plans, Sub-Processes, and Tasks with changes
in the new model. One such element can contain only one model-update process for each phase.
Model-update processes can import other modules, which are common for the model update phase. However, note
that the imported modules do not have access to the old or new model and must import the models explicitly if
necessary.
Model update processes exist in their own contexts, separated from the model instances that are updated. However,
they have access to the relevant contexts:
• Relevant for their phase:
– Pre-processes have access to the old model instance.
– Post-processes have access to the new model instance.
• Relevant for their model element.
– Accessible Namespaces and Contexts
Defined for Element
Accessible Context and Namespace
Module
Module namespace
Process
Process and anything above
Plan
Plan and anything above
Embedded Sub-Process
Sub-Process namespace and anything above; for multi-instance sub-processes also
their iterator
Parameters of the sub-process and anything above; for multi-instance also subprocesses their iterator
Reusable Sub-Process
Task
Task parameters and anything above; for multi-instance Tasks also their iterator
308
Model Update
If a name clash occurs, for example, if a pre-process context variable has the same name as a variable in the
old model, the name in the namespace with higher priority "overshadows" the name in the namespace with lower
priority.
The namespace priority from the highest to the lowest is as follows:
1. Local namespace of the model update process
2. Contexts of the element the model update process is attached to:
• If on activity, the parameters of the activity
• If on a module, process, plan, or sub-process, the namespace of the element
• If on a multi-instance activity, the iterator of the activity
• Imports of other modules and global model update variables
Note that model update processes do not have access to each other. However, you can define context variables
which are shared by all update processes in the given update phase or use signals between model-updates of the
same phase. Model update processes of different phases cannot access each others‘ context nor can they share
their context variables.
• Model Update Logs
• Updating a Model
4.3
Model Update Logs
The logs from a model update procedure are available in the Model Update Logs view. Also you can open the Model
Update Detail view of individual model updates from the Model Update Logs view.
Entries in the list of model updates show:
• Source Model: source model name and version, and time of its upload
• Target Model: target model name and version, and time of its upload
• Started: date and time when the update procedure was started
Table with details on updated model instances (below the list of model updates) contains:
• Model instance ID: identifier of the updated model instance
• Started: date and time when the update procedure was started
• Finished: date and time when the update procedure was finished
• Result: result of the update of the model instance (see GO-BPMN Modeling Language Specification).
In the view toolbar in the upper right corner of the Model Update Log view, Export MUC (
).
4.4 Defining Model Update and Updating Model Instances
309
Model Update Detail
The Model Update Detail view contains details about the update of a model instance.
To display the view, click the model instance ID in the Model Update Logs view. The view, contains:
• General area:
– ID: model instance ID
– Date: date and time when the model instance was updated
– State: model instance execution status (see GO-BPMN Modeling Language Specification)
– Source Model: name and version of the source model and its upload time
– Target Model: name and version of the target model and its upload time
– Update Log area: details on update procedure
Figure 4.4 Model Update Detail
4.4
Defining Model Update and Updating Model Instances
If you want to update non-finished model instances, so they run according to another model, you will generally
proceed as follows:
1. Import the model you want to update into your workspace: note that you can download the model from the
server either using the Management perspective or the Management Console.
2. Create a copy of the model and modify it to become your new model: make sure to keep this original model
unmodified.
3. Create a model update definition file for the original and new model and define in it the instructions on how to
handle differences between the models.
4. Upload the new model to the server.
5. Update the model instances of the model from the Management perspective or the Management Console,
use the model-update configuration to update model instances of the model).
310
4.4.1
Model Update
Creating a Model Update Configuration
How a running Model instance is updated is defined in a Model update configuration file. This definition file stores
mappings between modeling elements of the old and new model as well as all the related update data, such as,
update pre-condition, model-update processes, transformation expressions, strategies, etc.).
Note: Model update configuration ignores disabled elements.
Before creating the definition, make sure your workspace contains both: the source (old) module and the target
(new) model.
To create a model update configuration:
1. Go to File > New.
2. Select Model Update Configuration.
3. In the New Model Update Configuration dialog box, type the path to the source (old) and target (new) models.
4. Click Next.
5. In the updated dialog box, select the parent project where you want to save the model update configuration.
In the File name text box, type the configuration name.
6. Click Finish.
Important: When the model-update configuration is being generated, the system attempts to map
the old elements to their updated new counterparts, and uses default transformation strategies.
The proposed mapping might not be accurate and it is strongly recommend to review the file
thoroughly.
7. In the model update configuration, do the following:
• check the element mapping (refer to Changing Element Mapping),
• define data type transformation (refer to Defining Data Type Transformation),
• define variable transformation (refer to Defining Variable Transformation),
• define modeling elements transformation (refer to Defining Process Element Transformation).
8. Whenever you change the sources (old and new models), refresh the configuration: In the GO-BPMN Explorer, right-click the configuration and select Refresh.
A new model update configuration appears in the specified project in GO-BPMN Explorer and the Model Update
Configuration Editor with the created configuration opens. Note that the configuration has the default update strategies on modified elements of the entire model. You might want to change that. Since the mapping and the update
strategies are generated, you might need to edit these manually too. The file must contain update rules for all
relevant elements; it is not possible to create a model update configuration for a part of the model.
4.4.1.1
Copying Model Update Data
Once you have defined the update data on a Module, that is, transformations and model update processes, you can
copy the data and paste it into another model update configuration.
Note that pasting works only if the Module name is the same as the original Module and the type of update data is
correct, that is, you cannot paste model update data from variables to data types.
To copy the variables, processes, or data type update data, do the following:
4.4 Defining Model Update and Updating Model Instances
311
1. Open the .muc file.
2. Open the tab with the respective data.
3. Right-click the module and click Copy Module Configuration.
4. Open the target .muc file and the tab with the model update data.
5. Right-click the target module and click Paste Module Configuration.
Figure 4.5 Copying model element changes on a module
4.4.2
Editing Model Update Configuration
Important: The model update definition is edited in the Model Update Editor, which is based on the
Comparison Editor. It is strongly recommended to refer to the documentation on comparing before
using the Model Update Editor.
The Model Update Configurations are edited in the model update multi-page editor, which is by default associated
with model update configurations (.muc).
The editor opens the configuration with the update rules sorted on the following pages:
• Overview with general model update information and settings
• Data Types with differences on data types and their transformation expressions
• Variables with differences on variables and their transformation expressions
• Processes with differences on processes and their elements and their strategy as well as their model update
process references
Pre-processes and post-processes are displayed in the GO-BPMN Explorer under the model update file configuration.
312
Model Update
Figure 4.6 Model Update Editor
Every page contains the following:
• Baseline column with the resource with the change
• Modification column with the respective change marker and its description (see Comparison Editor);
• Transformation/Strategy column with data on how to handle the difference.
Note: On tool launching, the continues transformation strategy for process element with a change is set.
Consider changing the value.
• The Processes page contains also the Pre-process and Post-process columns with model-update processes
for relevant changes.
Note: Changes on local variables are displayed in the processes page below the respective parent element.
4.4.2.1
Displaying Matching Data
When the user creates a model update definition (.muc) file the system automatically maps the elements of the old
model to the elements of the new model and compares the models. Based on the diff, the editor provides options
for update rules.
To display also the matched data, which is hidden by default, do the following:
4.4 Defining Model Update and Updating Model Instances
313
1. Open your .muc file in the Model Update Editor.
2. Click the Filter button (
).
3. In the Differences Filter dialog box, select Matched Properties and Elements Without Changes as required.
4. Click OK.
4.4.2.2
Changing Element Mapping
When the user creates a model update definition (.muc) file the system automatically maps the elements of the old
model with the elements of the new model and performs diff of the models. If the automatic mapping is incorrect,
you need to adjust it manually.
Note: When changing mapping, you can match only elements with the same parent and of the same type. Recognized element types are start event, intermediate event, task, sub-process, plan, and process.
To change or cancel the mapping of an element, do the following:
1. Open your .muc file in the Model Update Editor.
2. Display the matched elements if necessary (click the Filter (
Changes).
) button, and select Elements without
3. In the Model Update Configuration Editor, right-click the element entry with the incorrect mapping.
4. In the context menu, select the applicable option:
• Change Source of Mapping; in the Change Source of Mapping dialog box, select the required source
element
• Cancel Mapping
4.4.2.3
Changing Model Update Settings
Model update configuration defines multiple properties that are used to control the update process.
To change general model update settings of your model update configuration, do the following:
1. Open the model update configuration (.muc) and in the Model Update Editor, the Overview page.
2. On the Overview page in the Settings area, define the model update settings:
• Source (old) and target (new) model
Make sure to refresh the definition if the source or target model has been changed.
• Override source/target model hash
The source and target models are identified by their hash codes, which change whenever a changed
Model is uploaded to the server. Therefore it is not possible to apply a model update configuration on
Model instances of Model that were changed after the model update configuration was created. If you
want to enforce a changed hash code anyway, select the option and enter the Model hash code below.
• Model update pre-condition
This Boolean condition is checked when a model instance update is triggered: If evaluated to false, the
model update is rejected and the execution of the model instance continues.
314
Model Update
• Trigger model transformation automatically enables and disables automatic start of transformation
phase of the model update
If false, the transformation phase must be triggered manually by the user.
• Select Trigger post-processing automatically enables and disables automatic triggering of postprocessing phase after transformation
If false, the post-processing phase must be triggered manually by the user.
Figure 4.7 Changing hashcode of the target Model
3. Click OK.
4.4.2.4
Defining Transformation
When defining transformation for added and changed records or fields and changed variables, it is defined as a
transformation expression, while updated modeling elements require a transformation strategy and possibly model
update processes. For details on the concepts behind transformation, refer to Transformation.
When model update configuration is created or refreshed, the system attempts to provide automatic transformation
rules for changed entities. If this is not possible, the entity entry is highlighted. To change the default transformation
strategy or expression, go to the entry in you muc file and click the Transformation cell.
4.4 Defining Model Update and Updating Model Instances
Figure 4.8 Defining variable transformation expression
Figure 4.9 Selecting transformation strategy
4.4.2.4.1
Defining Process Element Transformation
To define transformation strategy for elements, do the following:
315
316
Model Update
1. Open the model update configuration.
2. Click the Processes page title in the lower part of the Model Update Editor.
3. Click the Transformation/Strategy column in the row with desired element entry and select Continue or
Restart. If the strategy of a parent element is set to Restart and the child element has the strategy Continue, the Continue strategy will be never applied since the parent element will be always restarted.
4.4.2.4.2
Defining Data Type Transformation
Transformation of data types on model update is defined in the model update configuration as an expression. The
expression defines how the value of every instance of the old data type is transformed into the new data type value.
It typically contains a reference to a record property.
Important: It is not possible to define a transformation for the field type of a Shared Record to a field of another
type for a Shared Record, since such a process requires database migration.
To define transformation expression for data types, do the following:
1. Open the model update configuration.
2. Click the Data Types page title in the lower part of the model update editor.
3. Click the Transformation column in the row with an added or modified data type and then the Browse button
on the right.
4. Specify the transformation expression.
Figure 4.10 Defining data type transformation
The data type transformation is defined for a Book record:
• The ISBN record field has changed from Integer to String. The old ISBN instances will be transformed
using the toString(old("ISBN")) expression.
• The field genre of the Book record was originally of the String type. In the new model, the field is an
Enumeration. Any instances of the field will be transformed to their value with the switch expression.
• On the related Author Record, the fields firstName and surname have been removed and the record
field name has been added. The new field will be populated with the concatenated version of the
removed fields. Note that the function old() returns as an Object and therefore the call must be
wrapped into a toString() function call.
4.4 Defining Model Update and Updating Model Instances
4.4.2.4.3
317
Defining Variable Transformation
Variable transformation is defined by a transformation expression in the model update configuration and takes the
form of a closure. It returns a value of a basic data type evaluated within the old model instance.
To define transformation strategy for variables do the following:
1. Open the model update configuration.
2. In the Model Update Editor, do one of the following:
• For local variables, open the Processes tab and expand the parent element of the local variable.
• For global variables, open the Variables page.
3. Click the Transformation column in the row with the variable and click the Browse button on the right.
4. In the Transformation Expression Editor dialog box, click the Edit button and specify the transformation expression in the Expression Editor. The transformation expression returns the new value of the variable: To
use a value from the old context use the old() function call.
4.4.2.5
Creating a Model Update Process
Model update processes in model update definitions are defined in the model update configuration per relevant
process element. They serve to prepare an instantiated element for transformation (pre-processes) and for renewed
running of the model instance after transformation (post-processes).
To create a model update process, do the following:
1. Open a model update configuration in Model Update Editor.
2. Open the Processes page.
3. Right-click the row with the element entry with the respective change (module, process, plan, sub-process,
behavior, or task).
4. In the context menu, select Create Pre-process or Create Post-process.
A new page with the model update process appears. Note that all model update processes are displayed in the
GO-BPMN Explorer under the .muc file. Design the model update process as a common BPMN-based process.
4.4.2.5.1
Importing Module to Model-Update Processes
To import modules so that they are available to all pre- or post-processes of a model update, do the following:
1. In GO-BPMN Explorer, expand your muc file.
318
Model Update
2. Right-click the Pre-processing or Post-processing directory and click Add Import.
Figure 4.11 Importing a module
3. In the Add New Import dialog, select the module and click OK.
4.4.2.5.2
Creating Context Variables for Model Update Processes
To create context variable for the pre-processes or post-processes of a model update, do the following:
1. In the GO-BPMN Explorer, locate the muc file.
2. Expand the muc node.
3. Right-click the Pre-processing or Post-processing directory and in the context menu, select New > Context
Variable.
4.4 Defining Model Update and Updating Model Instances
319
Figure 4.12 Creating variable in a model update process
4.4.2.5.3
Editing a Model Update Process
To edit a model update process, do the following:
1. In the Model Update Editor, open the .muc file and then the Processes page.
2. Right-click the row with the required element entry.
3. In the context menu, select Open Pre-Process or Open Post-Process.
4. In the Process editor, edit the Process and save. Alternatively, double-click the model update process in the
GOBPMN Explorer under the muc file.
4.4.2.5.4
Deleting a Model Update Process
To delete a model update process from your muc file resource do the following:
1. In the page title bar (at the bottom of the editor), click the Processes page tab.
2. Right-click the row with the element, for which you wish to delete a model update process.
3. In the context menu, select Delete Pre-Process/Delete Post-Process.
320
4.4.3
Model Update
Updating Model Instances
Before updating model instances, make sure the new Model (target) is uploaded. Note that only model instances
that are Running, Suspended, Updated, or Update Aborted can be updated.
Note: When updating Model instances their IDs are preserved and the rules defined in the Model
update configuration are applied (for details see GO-BPMN Modeling Language Specification).
Note: It is not possible to update a model to a model with a different version of Standard Library.
To update model instances, do the following:
1. Open the Model Instances view.
2. Click the Update (
) button in the view toolbar.
3. In the Model Update dialog box, specify the model update configuration and data mapping file to be applied:
• Click Workspace Resource to select a configuration/data mapping file from the current workspace.
• Click External File to select a configuration/data mapping file from other location.
4. Click Next.
Figure 4.13 Model update dialog
4.4 Defining Model Update and Updating Model Instances
321
5. On the Filter page, define the filtering criteria for model instances and click Apply Filter if applicable. You
may apply also a previously defined filter definitions. However, status and model criteria is ignored (model is
defined in the Model Update Configuration).
6. In the Model Instances area, select the model instances you wish to update.
Figure 4.14 Model update dialog box with filtered Model instances
7. Click Next and Finish.
This triggers the model instance update: The model instance is suspended if not suspended already, becomes
read-only and the model update process is performed.
Note: On update, the closures of a model instance are checked for compatibility. If an incompatible
closure is detected, the system displays a dialog with details on the closure with incompatibility.
8. After the update has finished, the model instances remain in the status Updated and are still not running. To
resume the instances, click Resume in their context menu.
322
Model Update
Figure 4.15 Updated model instance with details on the update process
To resume multiple instances, click Resume All Updated in the context menu: note that the option resumes the
model instances that are displayed in the view. The set of the displayed instances is defined by the Filter of the view.
4.4 Defining Model Update and Updating Model Instances
323
If a model update remains hanging in the pre-processed status, check the respective model instance detail views
and the Model Update Logs view the update process may be waiting for manual triggering of its transformation or
post-processing phase which is set in the model update configuration.
You can abort model updates from the Management perspective or the Management Console, and resume them by
) button in the Model Instances view (select the respective model instances
clicking the Continue Model Update (
in Pre-processed or Transformed status first).
After the update has finished, the model instances remain in the status Updated and are still not running. To resume
the instances, click Resume in their context menu.
To resume multiple instances, click Resume All Updated in the context menu: note that the option resumes the
model instances that are returned by the Filter of the view.
4.4.3.1
Downloading Model Update Configuration
To download a model update configuration from the LSPS Server, do the following:
1. Open the Model Update Logs view.
2. Select an update log.
3. In the view toolbar, click the Export MUC (
4. Define the target location and file name.
) button.
324
Model Update
Chapter 5
Appendix: User Interface
The development environment of Living Systems® Process Design Suite is based on the Eclipse framework and
uses many of its features.
Note: Since the environment features are well documented in the Eclipse help (refer to http←://help.eclipse.org), this document deals only with some of the features and focuses on the
product-specific features.
5.1
Workspace
The user interface operates over data in a particular workspace. A workspace is a directory on your file system.
Resources in the workspace are available to the PDS environment. The environment comes with editors and various
tools for working with the resources.
A Workspace is a set of resources and settings you work with during your session: it includes the directory with
your directories and files, which are displayed in the GO-BPMN Explorer view and the configuration of your working
environment, such as, layout of view, run configurations, etc.
You are always prompted to select the workspace when you start up the Process Design Suite and you are free to
switch to another workspace at any point.
5.1.1
Switching Workspace
To switch to another workspace, do the following:
1. Click File > Switch Workspace.
2. In the Switch Workspace submenu, do the following:
(a) Select the required workspace.
(b) Click Other and in the Workspace Launcher dialog box use Browse to locate the workspace folder.
Note: To create a new workspace in the location, enter a new workspace name.
The Process Design Suite is restarted and loaded with the new workspace content.
326
Appendix: User Interface
5.2
Perspective
A perspective is a group of views, editors, and control items in the workbench with related purpose, which defines
their default layout and the set of available commands in tool bars and menus (effectively, it is the "stuff" you see).
Living Systems Process Design Suite contains the following perspectives:
• Modeling perspective for creating models
• Management perspective for management of model runtime
• Model Browsing perspective for presentation of models
The other available perspectives are Eclipse perspectives. You can create your own perspectives and adapt the
delivered perspectives as required.
Other available perspectives are Eclipse perspectives. For information on other perspectives, refer to http←://help.eclipse.org/ or the respective plug-in documentation.
5.2.1
Opening Perspectives
To open a perspective which was not previously displayed, do the following:
1. On the main menu, go to Window > Open Perspective > Other
2. Select the perspective.
Alternatively click the Open Perspective button (
5.3
) in the perspective switcher in the main menu.
Workbench
A workbench is the set of the views, toolbars, menus, and editors you use to work with your workspace resources.
Workbench accommodates perspectives. Perspectives define the views, editors and control items relevant to the
given perspective.
The upper part of a workbench shows bars and menus with commands for the entire workbench:
menu bar provides access to features applicable for the entire workbench, including commands for perspectives.
Menu commands in the toolbar might appear and disappear depending on the active perspective.
Figure 5.1 Menu bar
5.4 Views
327
main toolbar contains buttons with functionalities applicable to the current active workbench. The functionalities
are available also in the menu bar. Its content can change depending on the settings of the active perspective.
perspective switcher contains button with perspectives, which were already displayed and allows you to display
other perspectives as well.
Figure 5.2 Workbench
1: menu bar; 2: main toolbar; 3: perspective switcher
status bar located in the bottom trim of the workbench contains the name of the current server and the active user
login as well as information on compiling or connection establishing.
Figure 5.3 Status bar
5.4
Views
Views are windows that contain a particular type of information and allow you to perform particular types of action
on their content: they allow you to navigate through resources, work in editors, or provide alternative presentations
of resources. Views are displayed in a perspective.
328
Appendix: User Interface
A view can be displayed and focused manually by the user or automatically when called by a tool or action (for
example, when a search action is performed, the Search view with results appears and is focused regardless of
whether it was displayed before).
Views generally contain the following:
Figure 5.4 View toolbar with the view titlebar and function buttons applicable to the content of the
respective view
Views have context menus:
• System menu with commands for layout Customizing To display the system menu, right-click the title bar of
the view.
Figure 5.5 System menu
• View menu with commands that apply to the items displayed in the view
5.4 Views
329
Figure 5.6 View menu
To display the pull-down menu, click the triangular button in the view tool bar
• view content (list of resources, errors, etc.)
Every view can be docked, stacked or detached, minimized and maximized, and closed and restored as needed.
5.4.1
Displaying Views, Tabs and Pages
To display a view, do the following:
1. Under the Window menu select Show View.
2. Choose the view.
To display a view, which is not listed, such as a view of another perspective, click Other, under Process Design Suite
select the view, and click OK.
330
Appendix: User Interface
Figure 5.7 The Show View dialog box
5.4.2
Changing View Position and Detaching Views
To change the position of a view or to detach it from the workbench, do the following:
1. Click and hold the view by its title bar.
2. Drag the view to the required position within or out of the workbench.
When dragging the view, the mouse pointer turns into a drop cursor to indicate the currently available docking
position.
Drop Cursor
Indicated Docking Position
Docking along the nearest border in the indicated position
Detaching view from workbench
Stack view as a tab
To integrate a detached view into the workbench, right-click the view title bar and unselect Detach.
5.5 Editors
331
Figure 5.8 Integrating a detached view
5.4.3
Using Fast View
With Fast View, you can hide views while keeping their icon in the trim of the workbench similarly to minimizing
views in your OS.
If you click a fast view icon, the view is displayed; when you click it again, the view is hidden. To activate Fast View
to a displayed view, do the following:
1. Right-click the view title bar.
2. Select Fast View.
Alternatively, click the Show View as a fast view button in the trim on the bottom of the workbench and select
a view.
Note: By default, Fast View icons are docked in the trim on the very bottom of the workbench.
Drag them anywhere along the workbench edges to change this position.
To disable the Fast View feature, right-click the fast view icon and uncheck Fast View or click the Restore icon.
5.5
Editors
To edit resources of the Process Design Suite, the product provides default embedded editors, which open automatically in the editor area when the user double-clicks a resource file in a navigation view, for example, GO-BPMN
Explorer.
You can open any resource using custom editors by right-clicking the resource and selecting Open With.
As you open multiple resources for editing, they are stacked behind each other in the editor area.
332
Appendix: User Interface
Figure 5.9 Editor area with multiple editor tabs
Note: When editing resources in editors, an asterisk appears in the editor label to indicated unsaved
changes on the resource.
• Modeling Tools
5.6
Modeling Tools
Living Systems® Process Design Suite provides view, editors, and other tools that serve to create projects, modules,
resource files (processes, global variables, custom data types, etc.) and the resource content.
The tools are by default available in the Modeling perspective of Living Systems® Process Design Suite.
5.6.1
Modeling Perspective
The Modeling perspective is a perspective intended for designing models and working with their resources: in its
default layout, it contains a set of views intended for GO-BPMN modeling.
Note that you can customize the perspective, and add or remove views, even views that are not related to modeling.
5.6 Modeling Tools
333
Figure 5.10 The Modeling Perspective
5.6.1.1
Opening the Modeling Perspective
To open the Modeling perspective, go to Window > Open Perspective.
• Select Modeling.
• Select Other and Modeling in the Open Perspective dialog box.
Note: Alternatively, activate the perspective by clicking Modeling in the perspective switcher or the link
on the Welcome page.
5.6.2
Modeling Views
PDS contains a set of views that allow you to work with modeling resources.
5.6.3
GO-BPMN Explorer
The GO-BPMN Explorer is a view for navigation through workspace resources.
The view is displayed by default in the left part of the Modeling perspective and contains an expandable tree with
GO-BPMN projects available in the workspace and their content (resources, elements, etc.).
Note that items have context menus with the functionalities that apply to the particular item type: the context menu
of a GO-BPMN Project contains other options than the context menu of a process definition.
334
Appendix: User Interface
Figure 5.11 GO-BPMN Explorer with Resources
The GO-BPMN Explorer view provides additional features available in the context menus of individual elements
displayed in the view. The context menus differ, depending on the selected resource.
5.6 Modeling Tools
335
Figure 5.12 Context menu of a module
5.6.3.1
Filtering in GO-BPMN Explorer
Filters of the GO-BPMN Explorer allow you to hide or show chosen types of elements or elements with a particular
modeling status.
To apply a filter on the entries of the GO-BPMN Explorer:
1. In the GO-BPMN Explorer toolbar, click the view menu button and (
2. In the displayed dialog box, select what items to hide:
• Any elements with the selected modeling status
• All elements of the selected type
) select the Filters (
) button.
336
Appendix: User Interface
Figure 5.13 GO-BPMN Explorer filtering
3. Click OK to apply the filter.
5.6.4
Outline View
The Outline view shows the outline of the diagram displayed in the editor.
For resources, which contain diagrams or graphical representations (such as Form editor), the activated diagram or
resource is shown. Otherwise, it remains empty.
In the Modeling perspective, the Outline view is by default shown in the left lower part of the workbench.
5.6.5
Properties View
The Properties view contains tabs with properties of the selected element or resource file. The view is updated
whenever you select an item in the GO-BPMN Explorer or an editor.
Note: Note, that if you select an item in the GO-BPMN Explorer, and the item is not opened in an editor,
the Properties view is in read-only mode.
5.6 Modeling Tools
337
The view contains tabs that show the related properties for the selected item: Note that tabs vary depending on the
item (only relevant tabs are available). The tabs include the variables and parameter tabs of the items if applicable.
Figure 5.14 Properties view of a task
In the Modeling perspective, the Properties view is displayed by default in the lower part of the workbench.
Detailed description of properties of individual items, such as modeling elements and resource files can be found in
this document as well as in the GO-BPMN Modeling Language User Guide and Standard Library Specification.
Figure 5.15 Imports Tab
The Imports tab is available for modules and shows the imported modules. In the pane, you may add or remove
imported modules (refer to GO-BPMN Modeling Language User Guide).
5.6.6
Problems View
The Problems view shows a list of validation problems detected in the opened GO-BPMN projects (closed project
are not validated).
Problem notifications are issues, which cause validation problems. Problems are categorized and provided markers
indicating their severity (refer to Problem Severity).
Each problem entry contains the following:
338
Appendix: User Interface
• description;
• resource;
• path;
• location;
• type.
Note: Problem type may differ, though mostly it has the “GO-BPMN Problem” value; for information
about other problem types refer to www.help.eclipse.org or documentation of the respective plug-in.
After double-clicking a problem entry, the associated editor with the problem object appears.
View Menu (
) contains the following commands:
• Show: for displaying and hiding errors and warnings
• Group by: for grouping of problems depending on various criteria
• Sort by: for sorting of entries by one of their attributes
• New Problems View: for displaying of another Problems view
• Configure Content: for configuration of problems
• Columns: for configuration, and displaying and hiding of columns with details
• Preferences: for configuration of the available column and number of displayed items.
In the GO-BPMN perspective, the Problems view is by default shown in the lower part of the workbench stacked
behind the Properties view.
5.6.7
Error Log View
The Error Log view captures all events logged by the Process Design Suite.
For each error, an error entry is presented in the view. Every error report contains information about the plug-in that
generated the error, and date and time when the error occurred.
Double-clicking an error entry opens the Event Details dialog box with details about the respective error message
including the date, when it appeared, its severity, error message, and the exception stacktrace.
The view toolbar contains buttons allowing the user to export (
Console view (
restore logs (
), clear log view (
) and import logs (
), and delete log entries (
), and apply filters to the displayed items (
), show stack trace in the
), open the current log and edit it (
),
) (for further information see http://help.←-
eclipse.org).
Note: Error Log may contain also error entries of the server (if these were caused by a Process Design
Suite feature), which appear primarily in the Console view.
5.6 Modeling Tools
339
Figure 5.16 Error Log with error entries
5.6.8
Search View
The Search view lists out search results meeting the previously defined search criteria.
The results are shown in an expandable tree structure. The Search view is not displayed by default, however, it
appears automatically when performing a search (see Search)
5.6.9
LSPS News View
The LSPS News view is a view with RSS feed of the LSPS. The view is not displayed by default: Go to Window
Show View Other and in the displayed dialog, search for LSPS News.
Figure 5.17 LSPS News view with RSS feed entries
340
Appendix: User Interface
5.6.10
Modeling Editors
Process Design Suite comes with a set of editors for individual resource types of GO-BPMN projects (configurations
and definitions).
Different project resources require different editors. The program launches the native default editor when you
double-click the resource file in the GO-BPMN Explorer. However, you may open a resource also with an external
editor.
If several editors are opened at the same time, their tabs are stacked behind each other in the editor area.
Process Design Suite provides the following editor main types of editors:
• form-like editors
• diagram editors
Editor of the form-like and diagram type have common features and feel similar though you edit various resources.
Apart from editors of these type, PDS comes with other editor with features specific for editing of a particular source
types:
• Export Configuration editor
• Form editor
• Model Update Editor for model update configurations
• Web Services Editor for definition of Web service resources
5.6.10.1
Form-Like Editors
Form-like editors allow you to edit particular types of resources in a similar graphical user interface.
Form-like editors are used to edit the following definitions:
• global variable definitions
• task type definitions
• function definitions
• query definitions
• localization definitions
• document definitions
• report definitions
• widget definitions
Form-like editors contain two areas:
• area with a definition list In the area, you can add or remove individual definitions and change their order if
applicable. You can also filter the list of definitions by entering the filtering value in the Filter field.
• detail area with details of the definition selected in the definition list The fields in the area depend on the
definition type.
Note: The detail area is visualized only if at least one definition entry is available.
5.6 Modeling Tools
341
Button
Add
Action
adds a new definition entry.
Remove
removes the selected definition entry.
Up
moves the selected entry up in the list.
Down
moves the selected entry down in the list.
sorts the list of entries alphabetically.
Sort is a toggle button: when activated, entries are sorted alphabetically and their order cannot be
changed; when deactivated, manual sorting using the Up and Down buttons is enabled.
You can display form-like editors in horizontal or vertical layout with the layout buttons (
right corner of the editors.
and
) in the upper
To copy and paste the definition entries, change their modeling status, disable them, or search for their usages,
right-click the entry in the area with the list and select the command in the context menu.
Figure 5.18 Context menu of a global variable definition
5.6.10.2
Diagram Editors
Diagram editors are editors for editing of Diagram resources. In these editors, you can edit the content of the
definition file on a canvas typically by dragging-and-dropping elements onto the canvas. The elements are added to
the definition and on the Diagram: Note that an element does not necessarily have to appear in a Diagram: it can
exist in the definition without its Diagram representation. Also one element can appear in multiple Diagram but is
still the same element that exists in the definition only once.
342
Appendix: User Interface
Note: A Diagram is a visualization of elements of a resource file that supports Diagrams and additional Diagram elements. Such a resource file can contain multiple Diagrams and an element from
the resource file can but does not have to be depicted in one or multiple Diagrams. Diagram visualize
their content in oriented graphs of element views, that is, pictures representing the element and its
relationships. Diagrams can contain the following:
• views which are graphical representations of elements from the definition; for example, a Diagram
in an organization definition can contain one or multiple views of any Role or Organization Unit in
the organization definition;
• diagram elements such as annotations; such elements do not have any semantic value for execution but serve to provide information to the user when they view the diagrams. For more
information on Diagram types, elements, and content, refer to GO-BPMN Modeling Language
Specification.
5.6.10.3
Export Configuration Editor
The Export Configuration Editor is used for specification of export configurations, which can be applied when exporting modules.
The editor is associated with export configurations with the .export extension and is launched automatically when such configuration is double-clicked in the GO-BPMN Explorer or when a new export configuration
is created.
An export configuration contains a list of resources, which are to be included in an exported file. The
resources specified may be: GO-BPMN projects, GO-BPMN libraries, GO-BPMN modules, or folders present in the
workspace.
Figure 5.19 Defining an export configurationcontent
5.6 Modeling Tools
Buttons available in the detail area:
343
344
5.6.10.4
Appendix: User Interface
Button
Description
Add
adds chosen resources to the export configuration file.
Remove
removes the selected resource(s) from the export configuration.
Form Editor
Form Editor is a WYSIWYM editor for forms, hence provides an approximate visual layout of the form. It is similar to
diagram editors with the palette with form components on the right but does not support Diagrams. The components
are placed on the canvas on the left.
Figure 5.20 Form editor
Further information and details on the editor features, form concepts and form-related features as well as multiple
form patterns are available in the Process Application Forms User Guide.
Was this manual useful for you? yes no
Thank you for your participation!

* Your assessment is very important for improving the work of artificial intelligence, which forms the content of this project

Download PDF

advertisement