Professional Documents
Culture Documents
1
4
8
9
11
14
16
17
26
28
30
32
34
37
38
39
41
42
45
49
54
55
57
58
61
63
66
67
69
72
73
74
76
77
79
81
85
87
89
91
94
96
97
100
102
104
Service components
108
Building a Decision service
112
Scenario: Creating a Decision service in a Personalized Notification
process
115
Adding a Decision service to a process
122
Implementing an activity using a Decision service
124
Attaching a Decision service to a decision gateway
125
Adding a BAL Rule component to a service
128
Creating rules using the rule editor
131
Business rule parts and structure
133
Defining variables in the rule editor
136
Copying and pasting content in the rule editor
138
Setting the rule language
139
Troubleshooting BAL rule editor errors
140
Adding and modifying Decision service variables
142
Default rule variables and parameters
146
Adding variable types and business objects to a Decision service
148
Variable types
150
Testing a Decision service
153
Debugging a Decision service
155
Exception messages in Decision service testing
157
Scenario: Exporting rules to a Rule Execution Server
160
Exporting rules for use in Rule Studio
163
Configuring a remote Decision service
165
Adding a JRules Decision Service component to a service
167
Adding a Decision Table component to a service
170
Authoring rules using JavaScript in a Decision Table component
172
Decision Table controls
174
Specifying variable values using JavaScript
175
BAL reference
176
Decision service limitations
177
Building a client-side human service
178
Building a heritage human service
180
Building an Ajax service
183
Building an integration service
184
Building an advanced integration service
186
Building a General System service
189
Modeling events
190
Event types
191
Modeling delays, escalations, and timeouts by using timer events
195
Modeling message events
198
Using start message events
201
Using intermediate and boundary message events to receive messages 205
Using intermediate message events and message end events to send
messages
209
Setting the target for a UCA message event
211
Using message end events
212
384
385
387
389
391
393
394
396
398
399
400
401
402
404
406
407
409
410
413
415
418
420
422
423
425
427
429
431
433
434
437
440
442
444
445
448
450
453
454
456
461
463
465
467
469
470
473
Variable types
475
Variable scope
477
Creating business objects
478
Shared business objects
480
Business objects, attributes, and variables that are renamed
482
Business object advanced properties
485
Declaring and passing variables
491
How variables are passed
493
Declaring variables
496
Mapping input and output data for an activity or step
498
Declaring variables for a subprocess
500
Testing declared variables and data mapping
502
XSD generation pattern for business objects
504
Using JavaScript in BPDs
506
Initializing complex variables
507
Creating exposed process values
508
Adding an EPV to a BPD or service
510
Adding an EPV to a report
511
Setting variables in pre and post assignments
512
Making business data available in searches and views
513
Creating user interfaces for business processes
513
Which artifacts should I use?
515
User interface concepts
517
Human services
519
Dashboards
520
Coaches
521
Coach views
523
Templates
525
Properties
526
General properties
527
Configuration properties and configuration options
529
Positioning options for coach view instances
533
Visibility properties
536
HTML attributes
538
Data binding for coach views
539
Binding data and configuration options
541
Boundary events
547
Event handlers overview
548
Framework managed versus view managed content for coaches
551
Controls
553
Advanced items for coach views
554
Content box
555
Custom HTML
557
Heritage artifacts
559
Difference between heritage human services and client-side human services
561
Difference between coaches and heritage coaches
563
565
568
572
574
575
577
582
584
586
588
591
594
596
596
597
599
600
601
602
604
607
610
612
614
617
619
622
624
627
629
631
633
636
637
639
641
646
649
651
652
654
656
657
658
660
661
664
667
673
676
678
680
683
687
690
697
701
702
704
705
706
707
708
709
710
713
715
717
718
719
721
723
725
726
727
729
730
732
733
734
736
740
741
742
743
744
745
746
747
750
753
755
759
760
761
763
764
766
767
768
769
771
772
773
774
776
777
778
780
782
786
788
789
791
792
794
796
798
799
800
801
802
804
806
807
808
809
810
812
813
815
817
820
824
827
829
831
840
841
controls the process at run time, the process is dynamic and influenced by current
events. As in a business process, the required activities must be completed.
However, optional activities do not need to be completed.
People who interact with other people, rather than automated programs, determine
the activities. To verify the complaint, receipts and invoices, which are external
documents independent of the case, must be captured. To implement these
activities with human services, subprocesses, services, and teams, you use the
same set of tools as you do to implement a business process.
Case management
You can define an unordered set of
activities that can be completed to solve
a business challenge.
The activities occur in an unpredictable
order.
The events determine the process. As
events occur, a worker selects the
appropriate activity. The resulting
process can vary depending on the
current event and the subsequent
selection by the worker. Activities are not
wired to one another.
Area
Main toolbar
Library
Description
Provides access to the
Designer view and
Inspector. Also provides
access to Process Center
and Optimizer if you open
the Process Designer
desktop editor. The main
toolbar is also where you
go to save all open editors,
take a snapshot, and view
web-based help.
Provides access to the
library items for the current
process application. You
can create and edit library
items, as described in
Managing library items in
the Designer view. Note:
Users who have
administrative access to
the application control
access to process
applications. For more
information, see Managing
access to the Process
Center repository.
Main canvas
Palette
Property manager
10
Advanced Integration
service
Ajax service
*
business object
*
BPD
*
case typeNote:Case
management functions are
only available if you have
IBM BPM Advanced with
the Basic Case
Management feature
installed.
*
*
11
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
12
web service
13
Process Designer
You can use several features in Process Designer to improve your efficiency.
When you start using the Designer interface in Process Designer, there are some
tips and shortcuts to keep in mind.
The following are tips and shortcuts for the Process Designer desktop editor:
- To maximize the space available for the main canvas, you can hide the library by
clicking the toggle at the bottom of the Revision History. You can also hide the
palette by clicking the left margin of the palette. Click the toggle icon and the
palette margin to restore the library and the palette.
- To move from one open library item to another, click the arrow keys or the menu at
the top of the window.
- Unsaved changes have an asterisk next to the item name at the top of the window.
- To create a new library item while you are working in the Designer view, press
Ctrl+Shift+N.
- To open an existing library item while you are working in the Designer view, press
Ctrl+Shift+O.
- To choose multiple items in a category, press and hold the Ctrl key and then click
each item.
- You can capture your development progress in snapshots as described in
Creating snapshots in the Designer view.
- You can revert to a previous snapshot (version) of a library item as described in
Reverting to a previous version of a library item.
- You can copy the previous snapshot (version) of a library item to your current
project as described in Copying an asset from a snapshot.
- You can add a dependency to a toolkit to use the library items from that toolkit as
described in Creating, changing, and deleting a toolkit dependency in the Designer
view.
- You can see updates that are made by other users as described in Concurrent
editing.
- For quick and easy access of particular library items, you can create favorites as
described in Creating favorites.
- To group library items for easy access, follow the instructions in Tagging library
items.
- To create smart folders of library items, follow the instructions in Organizing library
items in smart folders.
- To move or copy library items from one process application to another, follow the
instructions in Copying or moving library items.
- To add and manage external files as part of your IBM BPM project, see
Managing external files.
The following are tips and shortcuts for the Process Designer web editor:
- Click the "Hide the Library" icon at the top left corner of Process Designer to hide
the library.
- To maximize the space available for in the main canvas, you can resize the palette
and the main canvas and you can also hide the property manager by clicking the
arrow below the main canvas.
14
- To move from one open library item to another, click the arrow keys or the menu at
the top of the window.
- To choose multiple items in a category, press and hold the Ctrl key and then click
each item.
- You can capture your development progress in snapshots as described in
Creating snapshots in the Designer view.
- Unsaved changes have an asterisk next to the item name at the top of the window.
- You can add a dependency to a toolkit to use the library items from that toolkit as
described in Creating, changing, and deleting a toolkit dependency in the Designer
view.
- You can see updates that are made by other users as described in Concurrent
editing.
- To tag library items for easy access, follow the instructions in Tagging library items.
- To move or copy library items from one process application to another, follow the
instructions in Copying or moving library items.
- To add and manage external files as part of your IBM BPM project, see Managing
external files.
Parent topic:Getting started with IBM Process Designer
15
Concurrent editing
Multiple users can simultaneously access and change process applications and
library items in IBM Process Designer. When you edit concurrently, you
collaborate with other team members to create the library items that you need for
your project. For example, you can communicate about your ideas and edits with
instant messaging and see the results in the Designer view as they happen.
Note: Each user must be connected to the same Process Center and each user
must have write access to the process application or toolkit where the library items
are located. When you edit concurrently with other users, ensure that your
connection status is good.
When you are working in the Designer view, you can see when other users are
working in the same process application, as shown in the following screen capture:
You can also see when others are viewing or editing the same library item, as
shown in the following screen capture:
When multiple users work on the same library item, such as a human service, each
user can see the changes when edits are saved. To ensure that all users are aware
which library items are open and what changes are being made, Process Designer
provides the following notifications:
- When another user opens a library item by showing a user icon. You can hover
over the icon to see who that user is.
- When another user is editing a library item by displaying the words Read Only
next to the library item. When a user saves their work, the library item will be
available to edit.
- When another user has saved changes while you are editing a library item by
displaying the words Read Only next to the library item. When you click Save, a
Save conflict message displays to ask you either to save your changes and
override the other user's changes or discard the changes and accept the other
user's changes.
- When multiple users start to edit a library item at the same time, before the Read
Only text appears, by displaying a warning icon and message to suggest to each
user that they either immediately save their changes or discard them.
Parent topic:Getting started with IBM Process Designer
16
Setting preferences
IBM Process Designer provides several settings to control the appearance and
functionality of the editors and interfaces that it includes.
Capabilities
Decisions
JavaScript
Optimizer Settings
Description
Set the Blueworks Live server
URL and email address for
Blueworks Live process
subscriptions.Tip: Changing the
email address or the URL logs
you out of Blueworks Live.
Control the capabilities of the
current user. For example, to
create external activities in IBM
Process Designer, you must
enable IBM BPM Developer
Capability and IBM BPM
Advanced Features.
Control the locale setting for BAL
Rules.
Set preferences for the
JavaScript editor included in IBM
Process Designer. For example,
you can choose whether to
display JavaScript warnings.
Set options for the Optimizer.
For example, the KPI thresholds
that are used by the
Visualization Modes are the
thresholds from the current
working version of your process
application or toolkit. If you want
to use the KPI thresholds from
the snapshot (version) of your
process application or toolkit that
was most recently run and
tracked, change the Optimizer to
the following preference setting:
Use the KPI threshold values
from the actual version of the
Process App/Toolkit.
17
Passwords
Web Browser
Description
The Images Prefix
endpoint maps to the
AE_IMAGES_PREFIX
scenario key, which
configures the URLs that
are used in the Process
Designer authoring
environment to get images.
18
Additional Information
Information about using the
scenario keys to configure
the IBM BPM endpoints is
described in the topic
Configuring endpoints to
match your topology.
Portal Prefix
19
20
21
Specifies whether to
suppress the inclusion of
the user password in the
URLs that Process
Designer opens. For
example, each time you
run a playback in Process
Designer, a new Process
Portal browser session is
opened. Process Designer
then submits the user
credentials, which consist
of the user ID and
password, and the browser
session uses these
credentials to log in. The
suppressRedirectUrlPas
swd option stops the
Formatting Templates
merge="mergeChildren">
<formatting-templates merge="replace">
<formatting-template
comment="Currency" template="$
###,###,###.##"/>
<formatting-template
comment="Currency"
template="###,###,###.## "/>
<formatting-template
comment="Currency" template="
###,###,###.##"/>
<formatting-template
comment="Integer"
template="###,###,###"/>
<formatting-template
comment="Decimal"
template="###,###,###.##"/>
<formatting-template
comment="US phone" template="(###) 0000000"/>
<formatting-template
comment="US SSN" template="000-000000"/>
</formatting-templates>
</authoring-environment>
22
Inspector
merge="mergeChildren">
<sequenced-state-delta-manager>
<fallback-timeout>15
</fallback-timeout>
<slow-timeout>15
</slow-timeout>
<scheduled-timeout-padding>15
</scheduled-timeout-padding>
<time-in-fallback-before-link-reset>15
</time-in-fallback-before-link-reset>
<time-in-fallback-after-link-resetbefore-full-reset>15
</time-in-fallback-after-link-resetbefore-full-reset>
</sequenced-state-delta-manager>
</authoring-environment>
Mime Types
environment merge="mergeChildren">
<mime-types merge="replace">
<mime-type
type="application/javascript"/>
<mime-type type="application/octetstream"/>
<mime-type type="application/pdf"/>
<mime-type type="application/xml"/>
<mime-type type="application/xmldtd"/>
<mime-type type="application/zip"/>
<mime-type type="image/gif"/>
<mime-type type="image/jpeg"/>
<mime-type type="image/png"/>
<mime-type type="text/calendar"/>
<mime-type type="text/css"/>
<mime-type type="text/csv"/>
<mime-type type="text/html"/>
<mime-type type="text/rtf"/>
</mime-types>
</authoring-environment>
23
merge="mergeChildren">
<repository-ping-delay merge="replace">
</repository-ping-delay>
</authoring-environment>
24
25
Procedure
To create a new process application, complete the following steps:
1. Start the Process Designer desktop editor or enter the remote
Process Center URL into a web browser.
2. In the Process Apps tab, click the Create New Process App option.
3. In the Create New Process App window, enter a name, acronym, and description
of the process application. Ensure that the acronym for the process application is
unique and limited to seven characters. IBM Business Process Manager (BPM)
uses the acronym as an identifier for this process application and the library items
that it contains. For example, when you manipulate the items in the process
application with the IBM BPM JavaScript API, you can use the acronym to specify
the namespace of the items. For example, when you manipulate the items in the
process application with the IBM BPM JavaScript API, you can use the acronym
to specify the namespace of the items. The acronym for the process application
must be unique and limited to 7 characters. IBM BPM uses the acronym as an
identifier for this process application and the library items that it contains. For
example, when you manipulate the items within the process application with the
IBM BPM JavaScript API, you can use the acronym to specify the namespace of
the items.
Providing a description is optional. When you enter a description, you can view it
in the Process Center console by clicking the question mark next to the process
application name.
4.
If you are building cases in the process application, you can
select Allow users to open the process application in the web-based Case
Designer. For more information, see Opening Case Designer from Process
Center.Note:Case management functions are only available if you have IBM BPM
Advanced with the Basic Case Management feature installed.
5. To create library items in the process application, click the appropriate option:
- Open in Designer
Open in Case DesignerNote:Case management functions
are only available if you have IBM BPM Advanced with the Basic Case
26
Management feature installed. You see the Open in Case Designer option only
if you selected the option described in step 4.
What to do next
- To use tracks in this process application, enable the tracks in the Process Center
console.
- You can create toolkits to enable Process Designer users to share library items
across process applications.
27
Procedure
To import BPMN models into the IBM Process Center complete the following
steps:
1. Start the IBM Process Designer from your Windows desktop or using the URL for
the Process Center in a browser. The first time you start the IBM Process
Designer it opens to the Process Center console.You can trigger the import of the
models in two ways. You can either click Import Process App (on the Process
App tab), or Import Toolkit (on the Toolkit tab). Either of these actions will result
in an import window.
2. Click Import Process App. The Import Process App window displays.
3. Click Browse to select the BPMN 2.0 archive (.zip) file that you exported from
IBM WebSphere Business Modeler and click Next.
4. In the Import Process App window, a name and acronym have been specified
based on information in the file you selected. You can edit the name and acronym
and add a description. If you are using IBM BPM Advanced, you will see radio
buttons that you can use to choose what will be generated for unimplemented
services. Select either Advanced Integration Services or Integration Services
and then click Next. Note: Advanced integration services are only available for
unimplemented services. Integration services are always generated for
implemented services. Both radio buttons display only in IBM BPM Advanced. For
more information, see Building an Integration service and Building an Advanced
Integration service.
A Summary of the import results pane opens containing any generated error,
warning and information messages. A new process application or a toolkit is
created, containing the content from the BPMN 2.0 archive. It will include
integration services if the model contained web service bindings and advanced
integration services if the model contained unimplemented advanced integration
services. All Blueworks Live artifacts will also be integrated with a BPMN import if
Blueworks Live phases and other BPMN 2 extensions were in the model.
A snapshot of the process application is automatically created in the Process
Center, for your use as a baseline, in the future, if necessary.
28
5. You can filter the messages by clicking Errors or Warnings. Click Save and
specify a location if you want to save the messages. All the messages will be
saved as a text file even if a filter has been applied. Click Close.
What to do next
You have now imported your BPMN models successfully into the Process Center.
The following procedure helps you identify the step-by-step actions you will take
after a successful import. However these steps will vary depending on the contents
of your model and how you intend to make use of these models in the future. If you
had seen warning messages at the end of your import it is likely that you may need
to take some remedial action. Warnings usually indicate an unsupported construct
or invalid input model. For each warning, examine the contents of what was
generated and take additional action as required.
Parent topic:Building process applications
29
- Modeling processes
A process is the major unit of logic in IBM Business Process Manager (BPM). It is
the container for all components of a business process definition (BPD). Modeling
a good process that matches your requirements is at the core of Process Designer.
- Designing process interactions for business users
After you deploy a business process definition that you have built in Process
Designer to the Process Portal, a business user might interact with it in a number
of ways. The user might be the one to launch the process, or the user might be
assigned individual activities in the process.
- Enabling processes for tracking and reporting
IBM Business Process Manager provides ways to collect and consume process
performance information. To take advantage of this information, you enable to
design your processes to make them trackable.
Parent topic:Building process applications
30
31
Modeling processes
A process is the major unit of logic in IBM Business Process Manager (BPM). It is
the container for all components of a business process definition (BPD). Modeling a
good process that matches your requirements is at the core of Process Designer.
Many different individuals from various organizations are involved in developing
processes with IBM BPM. The overriding concern is to ensure that you are building
the best possible solution for meeting the stated goals of your project. To ensure
successful results, team members must work together to capture process
requirements and iteratively develop the model and its implementations, as specified
in the IBM Business Process Manager overview.
- Creating a business process definition (BPD)
To model a process, you must create a business process definition (BPD). A BPD
is a reusable model of a process that defines the common aspects of all runtime
instances of that process model.
- Building services
Use services to implement the activities in a business process definition (BPD).
When a BPD starts and the tasks within it are invoked, services perform the
required functions.
- Modeling events
Events in IBM Business Process Manager can be triggered by a due date passing,
an exception, or a incoming message from an external system. You can add
events to your BPDs that can occur at the beginning, during, or at the end of a
process. Use events to track data, manage errors, and retrieve information about
the execution of your BPDs.
- Documenting development artifacts
As you develop your process application, you might want to capture information
about the artifacts that you are creating. Each artifact in IBM Process Designer has
a documentation field for this purpose. You can enter text or links to external
resources such as web sites or attachments.
- Using external implementations
You can create external implementations for activities that are handled by
applications outside of IBM Business Process Manager. For example, you can
model an activity that is run by a custom Eclipse RCP or Microsoft .NET
application.
- Integrating with web services, Java and databases
You can configure IBM BPM processes to communicate with an external system
to retrieve, update, or insert data. And, external applications can call into IBM BPM
to initiate services. You can manage inbound and outbound communication with
external systems using undercover agents, web services, and integration services.
- Integrating BPDs with IBM Case Manager cases
To integrate with IBM Case Manager, you build an integration service and perform
other key steps when you want to integrate a business process developed in IBM
Process Designer with a case management case in IBM Case Manager.
Parent topic:Creating processes in IBM Process Designer
32
33
Procedure
34
36
Procedure
1. Open the Process Designer desktop editor.
2. Open a process application that contains a BPD.
3. Drag a lane from the palette and drop it onto the diagram.
4. In the Properties view, enter a name for the lane.
5. Optional: You can also associate a default team with the lane.When a user task is
added to this lane, the initial assignment for the task is the default lane team. If
you do not specify a default lane team, the default team is All Users.
6. Optional: You can also create a lane as a system lane, indicating that activities
within it are to be completed by an IBM Business Process Manager system. To
make a lane a system lane, select the lane in the diagram then select Is System
Lane in the Properties view. Although you can create a system task in nonsystem lanes, any new tasks in the system lane are created as system tasks by
default. After a system task is created, if you move the task to a non-system lane,
for example a lane associated with a team, it retains a system task type.
7. To reorder lanes with respect to one another, right-click a lane and select Move
Lane Up or Move Lane Down.
8. Click Save in the main toolbar.
Parent topic:Creating a business process definition (BPD)
37
Procedure
1. Open the Process Designer desktop editor.
2. Open a process application that contains a BPD.
3. In the Designer view, click the Diagram tab.
4. Drag an activity from the palette and drop it onto the diagram.
5. In the Properties view, enter a name for the activity.
6. Click Save in the main toolbar.
What to do next
After you add an activity to a BPD, you can change the type by selecting the activity
and choosing the implementation in the properties.
Parent topic:Creating a business process definition (BPD)
Related information:
Implementing activities in a BPD
38
Procedure
1. Open the Process Designer desktop editor.
2. Open a process application that contains a BPD.
3. In the Designer view, click the Diagram tab.
4. Drag the event from the palette. If you want to create a boundary event by
attaching an intermediate event to an activity, drop the event onto the activity
node. To verify the attachment, select the activity. If the outline of the activity
includes the event, the event is attached. By default, attached intermediate events
are Error events.
5. Select the event. In the event properties, click the Implementation option.
6. Select the type of event from the available options.
7. For attached intermediate events, select Interrupt activity if you want the activity
to close when the message is received.
8. In the Trigger section, you can select or create an undercover agent (UCA) to
attach to the event. See the topic in the related tasks section. Each event must be
associated with a UCA. When you run the process, the associated UCA carries
out the required action when the event is triggered.
Parent topic:Creating a business process definition (BPD)
Related information:
Creating an undercover agent
39
40
Procedure
1. Open the Process Designer desktop editor.
2. Open a process application that contains a business process definition (BPD) in
the Designer view.
3. From the palette, click to select the Sequence Flow tool.
4. In your process diagram, click the first modeling construct (normally the start
event), and then click the construct that follows the start event in the process flow.
The Sequence Flow tool connects the two items.
5. Continue creating sequence flows as needed. If more than one sequence flow
leaves the same modeling construct, the first one you add is the default sequence
flow. Subsequent sequence flows that originate from the same construct are only
followed under certain conditions. To specify the conditions under which a nondefault path is followed:
A. Select the sequence flow in the diagram.
B. In the Behavior section of the Properties view, specify the condition under
which the process execution follows this sequence flow. The default sequence
flow is followed whenever the conditions specified for the non-default flows are
not met. Conditions for all outgoing sequence flows other than the default
sequence flow are required or mandatory.
6. When you are finished establishing the process flow, click the Selection Tool in
the palette or press Esc to switch back to normal selection mode in the process
diagram.
Parent topic:Creating a business process definition (BPD)
41
Gateway type
Parallel (AND)
Inclusive (OR)
42
Description
Use a parallel, diverging
gateway when you want
the process to follow all
available paths.
Use a parallel, converging
gateway when you want to
converge all available
paths.
Use inclusive, diverging
gateway when you want to
follow one or more
available paths based on
conditions that you specify.
Use downstream of an
inclusive diverging
gateway to converge
multiple paths into a single
path after all the active
paths completed their
runtime execution. The
inclusive join looks
upstream at each path to
determine whether the
path is active, in which
case it waits. Otherwise, it
passes the token through
without waiting.
Exclusive (XOR)
Event
Procedure
1. Drag a gateway from the palette onto the diagram.
43
2. In the box that displays over the gateway, type a name for the gateway.
3. Create the necessary sequence flow to and from the gateway. The default
sequence flow is the first sequence that you create from the gateway to a
following activity. For a gateway, you can change the default flow by reordering
the sequence flow in the implementation properties.
4. Click the gateway in the diagram, and then click the General option in the
properties.
5. In the Behavior section of the general properties, click the list and select a
gateway type. The other fields described in the following table are optional:Table
2. Optional fields in the Behavior section of the general properties
Field
Name visible
Presentation Icon
Documentation
Gateway Type
Description
Displays the name that you provide for
the gateway in the diagram. Clear this
check box if you do not want the name
displayed in the diagram.
If you want to use an icon other than the
default provided by IBM Business
Process Manager, provide the path
name for the image that you want to
use. This option is not applicable to
exclusive gateways that are
implemented in human services.
Enter a description of the gateway.
Ensure that the type of gateway you
want to implement is selected from the
list. The preceding table describes the
types of gateways available. This option
is not applicable to exclusive gateways
that are implemented in human
services.
44
Example gateways
The following samples illustrate how to model several types of gateways.
When modeling processes or case instances in IBM Business Process Manager,
you have several options for implementing gateways. See Converging and diverging
flows to understand the available options and to see a sample implementation of a
parallel gateway. Review the following samples to learn more about exclusive and
inclusive gateways.
- To implement an exclusive and inclusive gateway in a business process definition
(BPD), you must declare variables for that BPD, as described in Declaring and
passing variables.
- To implement an exclusive gateway in a client-side human service, you must
specify the JavaScript conditions that determine the path to be followed by the
service flow, as described in Implementing exclusive gateways in client-side
human services.Restriction: Support for gateway implementation in human
services is provided for exclusive gateways only.
Note: If you want complex expressions to be used in gateway definitions, you can
enable an advanced editing feature in your preferences so that complex expressions
can be entered and customized. The default preference settings do not have the
advanced editing feature enabled. To enable the advanced editing feature, click File
> Preferences, expand IBM BPM > Capabilities > IBM BPM Advanced Features,
and then select Advanced Editors.
45
The default sequence path is selected in the Default Flow list, and is followed
to the Coach1 activity. Note that the default path is marked with a forward slash
(/) sign in the diagram. The sequence flow to Coach2 evaluates to false.
47
With exclusive gateways, only one available path is followed from the gateway. With
inclusive gateways or splits like the one described in the preceding example, one or
more paths from the gateway can be followed. The inclusive split gateway in the
preceding example determines the path or paths to follow based on the type of
customer that is processed. The conditions for this split are configured in the
implementation properties for the gateway as follows:
- If the value of the tw.local.customerType variable is "New", the path to activity 1
is followed.
- If the value of the tw.local.customerType variable is "New", the path to activity 2
is also followed.
- If none of the preceding conditions evaluate to true, the path to activity 3 is
followed.
Using this logic, you are able to run two separate activities for new customers and a
different activity when the customer is an existing one.
48
System Task
Description
Select this option if an
activity is to be started or
completed by a user
(human performer). For
example, if an activity
requires that managers
enter employee data,
choose User Task and
select or create a clientside human service or a
heritage human service to
implement the task.
Select this option if an
activity is to be completed
by an automated system or
service. For example, if an
activity requires integration
with an external system,
such as a database,
choose System Task and
select or create an
Integration service to
implement the task.
49
See...
Building a client-side
human serviceBuilding a
heritage human service
Service types
Decision Task
Script
Subprocess
Linked Process
50
Service types
Event Subprocess
None
Procedure
When the implementation that you want to use is created, such as a service,
complete the following steps to select it:
1. Open the Process Designer desktop editor.
2. Open a process application that contains a BPD.
3. Select the activity that you want to use in the BPD diagram, and then go to the
Implementation properties.
4. Under Implementation, select an option from the displayed list. For example,
choose User Task if the implementation for the current activity is a human
service with a coach. (The preceding table describes each available option.) Tip:
To implement the task as either a client-side human service or a heritage human
service, see Implementing a BPD activity as a human service.
51
5. Click Select to choose the implementation from the library. If the implementation
does not yet exist, click New to create it. (The previous table provides instructions
for creating implementations.) If you choose System Task for your
implementation option, you must specify extra properties, as outlined in the
following steps.
6. (System Tasks only) Select Delete task on completion if you want to run an
automated service that does not require routing. When you select this check box,
audit data for the task is not retained by the Process Server. By default, this
option is disabled.
7. (User Tasks only) In the Task Header section, specify the following properties:
Table 2. Properties in the Task Header section
Property
Clean State
Subject
Narrative
Action
Select to clear the runtime execution
state of an activity after it is complete.
By default, this option is disabled.
Enable this option only when you do not
want to store execution data (such as
variable values) for viewing after the
process finished execution.
Type a descriptive subject for the task
that is generated in IBM Process Portal
when you run the BPD. You can also
use the IBM BPM embedded JavaScript
syntax (for example,
<#=tw.local.mySubject#>) to express
the subject.
Type an optional description. You can
also use the IBM BPM embedded
JavaScript syntax to express the
narrative. Restriction: Do not use
JavaScript variable references in task
narratives if you need the data to be
available after the task completes.
When a task is complete, IBM BPM
removes the data for completed tasks to
conserve space. Instead, store the data
items in another location, such as a
database.
8. (User Tasks only) In the Priority Settings section, specify values as needed.Tip:
If you prefer to use a JavaScript expression with predefined variables to establish
the priority settings, click JS for options.
A. Under Priority, select one of the default priority codes from the list: Highest,
High, Normal (the default), Low, or Lowest.
B. Under Due In, enter a value in the text box and then choose Minutes, Hours,
or Days from the list. (When you choose Days, you can use the text box after
the list to specify hours and minutes.) You can also use the variable selector
next to the text box to choose an existing variable from the library. At run time,
the variable reflects the specified value for the time period. Select the required
52
53
Procedure
1. Open the Process Designer desktop editor.
2. Open a process application that contains a BPD.
3. Select the activity that you want implemented in the BPD diagram, and then go to
the Implementation properties.
4. From the Implementation list, select User Task, and then click Select next to
Default Human Service.
5. From the corresponding list, select the client-side human service or the heritage
human service to implement the user task. If the human service does not exist,
click New and complete the wizard steps to create the human service.
6. On the General tab, update the name of the user task as required, and then click
Save.Back in the Diagram view, when you double-click the task in the BPD:
- The Process Designer web editor opens if the task is associated with a clientside human service.
- The Process Designer desktop editor opens if the task is associated with a
heritage human service.
54
Multi-instance loop
Description
When you model a BPD activity with
simple loops, the required number of
instances is dynamically created, up to
the loop maximum value that you specify.
A simple-loop activity is run sequentially
until the last instance of the activity is
run. When you run an activity configured
for simple loops, a single token is
generated and used for each instance of
the activity, which, in effect, recycles the
runtime task.
A multi-instance loop dynamically runs
multiple unique instances of the same
BPD activity sequentially or in parallel.
When you run an activity configured for
multi-instance loops, a unique token is
created for each instance of the activity.
(For more information about tokens, see
Inspector reference.)
55
56
Procedure
1. Open the Process Designer desktop editor.
2. Open a process application that contains a BPD.
3. Select the activity that you want to configure in the BPD diagram.
4. Click the General option in the properties.
5. Under Behavior, select the Simple Loop option from the Loop Type list.
6. Under Simple Loop, type a value in the Loop Maximum box. This value sets the
maximum number of instances that can be created at run time. If you declare a
variable that can be used for this setting, click the variable icon to select it or type
the variable name into the Loop Maximum box.
7. In the Loop Condition box, type an optional JavaScript condition to dictate the
runtime loop behavior. A condition is evaluated before any instances are created
from the activity. If the condition is not met, the loop configuration does not occur.
8. Save your changes.
Results
When you configure an activity for simple loops, the activity includes the indicator
57
Procedure
1.
2.
3.
4.
5.
6.
Description
Resulting instances are run
sequentially until the last
instance of the activity is
complete.
Run in Parallel
Resulting instances are run at
the same time until all
instances are finished or until
the condition that you specify is
met.
8. For parallel ordering, select one of the following options from the Flow
Condition list:
Option
Wait for all to finish (All)
Description
Looping continues until all
resulting instances of the
activity are finished.
58
Procedure
59
1. In the BPD diagram, select the activity that you want to configure.
2. In the properties, select General.
3. Under Behavior, select Multi-instance Loop from the Loop Type list.
4. Under Multi-instance Loop, enter tw.local.ListofItems.listLength in the
Start Quantity box.
5. On Data Mapping, under Input Mapping, select, or type the following input
string: tw.local.ListofItems[tw.system.step.counter]
6. For the Ordering and Flow Condition settings, refer to steps 7 and 8 in the
procedure described earlier.
7. Save your changes.
60
Procedure
To assign a team of instance owners to a BPD:
1. Open the Process Designer desktop editor.
2. Open the process application that contains the business process definition (BPD).
3. In the BPD Overview, select a team for Instance owners, or create a new team.
To assign teams to lanes:
1. In the BPD diagram, click the lane in which you want to make the assignment.
2. In the Behavior section of the properties, click Select to choose the team that you
want to use as the default team for this lane. You need a default lane assignment
to ensure that any activities that are not otherwise routed have an automatic
default assignment. By default, the All Users team is assigned to each lane in the
BPD. You can use this default team for running and testing your BPD in the
Inspector. The All Users team includes all users in the system who are members
of the tw_allusers security group.Note: If the default team assigned to the lane
that is currently used for activity is changed, the team filter service definitions are
removed from the Assignments tab.
3. Choose the team from the library.
61
62
Procedure
1. Open the Process Designer desktop editor.
2. Open a process application that contains a business process definition (BPD).
3. Click an activity in a BPD diagram to display its properties.
4. Go to the Assignments page in the properties view.
5. From the Assign To list, choose one of the following options:Table 1. Assignment
Options
Option
Lane
Team
Description
Assigns the runtime task to the team
associated to the swimlane in which the
selected activity is located (the default
selection). If you select this option, you
can use a team filter service to
dynamically eliminate users from being
assigned to the activity.
Assigns the runtime task to a team. If
you select this option, you can either
specify a static team or use a team
retrieval service to dynamically select a
suitable set of users. In addition, you
can use a team filtering service to
remove unsuitable users from the team.
Assigns the runtime task according to
the policy that you establish.
Assigns the runtime task to an ad hoc
list of users.
63
Custom (Deprecated)
64
9. From the User Distribution list, choose one of the following options:Table 2.
User Distribution
Option
None
Last User
Load Balance
Round Robin
Description
IBM BPM assigns the runtime task to all
potential users (the default setting).
Assigns the runtime task to the user
who completed the activity that
immediately precedes the selected
activity in the swimlane. Do not select
this option for the first activity in a lane
unless the activity is a service in a toplevel BPD and a Start Event is in the
lane. In this case, the runtime task is
routed to the user who started the BPD.
From the potential users who can
receive the runtime task, IBM BPM
assigns to the users who have the
fewest number of open tasks,
regardless of presence.
From the potential users who can
receive the runtime task, IBM BPM
assigns to users in a round-robin
fashion. For example, if the users in the
Call Center team must receive the
runtime task, IBM BPM assigns each
task (created by each process instance)
in a series - to one user in the team
after another.
65
Procedure
If you are working with a business process definition (BPD), and want to assign an
activity to a dynamically retrieved team, complete the following actions.
1. Open the Process Designer desktop editor.
2. Open a process application that contains a BPD.
3. Open the diagram of your BPD and select the activity that you want to assign to a
team that is defined by a team retrieval service.
4. Go to the Assignments page in the properties view.
5. From the Assign To list, select Team.Tip: The Assign toLane option can also
be resolved by a team retrieval service if the team that is assigned as the default
team for the lane is a dynamically resolved team.
6. To assign the activity to an existing dynamically defined team, click Select then
select the name of the dynamically defined team.
7. To assign the activity to a new dynamically defined team, click New, provide a
team name, then follow the instructions described in Setting up a team retrieval
service.
Results
The team's members are determined dynamically by the appropriate team retrieval
service.
Parent topic:Assigning teams to BPD activities
66
Procedure
1. Open the Process Designer desktop editor.
2. Open a process application that contains a business process definition (BPD).
3. Open the diagram of your BPD and select the activity that you want to route.
Note: The activity that you choose must already have an attached service.
4. Go to the Assignments page in the properties view.
5. From the Assign To list, select Routing Policy (Deprecated).
6. Under Routing Conditions (If), click Add a column to select the variable to use
to begin specifying conditions.When defining routing conditions, you create a
table in which each column represents a variable and each row represents a
rule.
7. From the displayed list, choose the variable for which you want to specify a
condition.
8. In the first field in row 1, enter the value to compare to the variable.For example,
if you choose a variable called customer (String) in the preceding step and
that variable holds customer names, enter a customer name in the field.
9. If you want to add another variable to the routing condition, click Add a column
and choose a variable from the displayed list. Enter the value to compare to the
second variable.The following examples illustrate the syntax for possible values
in the variable columns:
Table 1. Routing conditions
Enter...
To match...
The exact string, ok (no
quotation marks)
Any number greater than 100
Any number less than 100
All numbers except 3
"ok"
>100
<100
!=3
10. If you want to establish advanced routing rules, select Adv. When you establish
routing rules, you create specifications that determine who receives the runtime
task, such as only those users who have a previously defined user attribute.To
67
establish rules, click Add Rule in the Advanced Assigned To (Then) section of
the Routing properties, and see Deprecated: Defining rules for instructions.
Note:IBM Business Process Manager creates only one set of rules under
Advanced Assigned To (Then) for the entire Routing Conditions table. If you
want to remove a rule after you define it, click Advanced Lane Participant in
the Assign To field in the routing conditions table to display the rule or rules for
that routing condition. Under Advanced Assigned To (Then), click the bullet
before the rule that you want to remove, and then click Remove.
11. If you do not select Adv, the Assign To field in the routing table shows the
default assignee, Swimlane, which means that the runtime task is routed to the
team assigned to the swimlane in your BPD. If you have multiple teams defined
in your current process application, you select one of those teams from the
menu.
What to do next
When you define routing conditions, IBM BPM evaluates the conditions in the table
from top to bottom. IBM BPM implements the first condition that matches. If no
conditions match, IBM BPM assigns the activity to the default assignee, Swimlane.
68
Description
Routes activities to users based on
whether they are the default lane
participants.
Selects users according to group
membership.
Selects users based on user attributes.
Selects users who match a particular
expression that you provide.
Procedure
1.
2.
3.
4.
5.
9. Click Add Decision to choose the type of rule to add.For example, you can
define the following Advanced Lane Participant group (team) rules in the group
properties:
Advanced Lane Participants are users who match all of the following rules:
- Who belong to the Finance Managers group
- Who have an attribute Level 1 Loans greater than tw.local.loanAmount
- Who match expression tw.local.Recipient
The Add Decision... option adds other rules to the list.
10. Supply the necessary information for the specified type of rule.
- For a Swimlane rule, supply the required input for the following specification:
Who belong to lane participant.
Table 2. Input required for a Swimlane rule
Specification
belong
Action
Click belong to choose either
belong or do not belong.
- For a Participant Rule, supply the input that you want for the following
specification:
Who belong to the select team .
Table 3. Input required for a Participant Rule
Specification
belong
Action
Click belong to choose either
belong or do not belong.
Click select team to choose a
team from the library.
select team
- For a User Attribute Rule, supply the required input for the following
specification:
Who have an attribute select user attributeequal toenter value.
Table 4. Input required for a User Attribute Rule
Specification
select user attribute
Action
Click select user attribute to
select a user attribute
definition from the library.
Click equal to to choose from:
equal to, not equal to, less
than, less than or equal to,
greater than, or greater than
or equal to.
equal to
70
enter value
- For an Expression Rule, supply the required input for the following
specification:
Who match expression enter value.
Table 5. Input required for an Expression Rule
Specification
match
Action
Click match to choose either
match or do not match.
Click enter value to display a
field in which you can enter
either an IBM BPM variable or
a JavaScript expression that
produces the value that you
want to compare. Be sure to
surround any strings in the
expression with double
quotation marks. The variable
or expression must evaluate to
a specific user name.
enter value
71
Procedure
1. Open the Process Designer desktop editor.
2. Open a process application that contains a BPD.
3. Open the diagram of your BPD and select the activity that you want to route.
4. Click the Assignments page in the properties view.
5. From the Assign To list, select List of Users (Deprecated).
6. In the Binding field, specify the variable that binds the list to the activity to be
assigned.For example, you can define a new complex variable that is a list (array)
to pass the list of users from the service that generates the list to the activity to be
assigned.
Parent topic:Assigning teams to BPD activities
72
73
Procedure
1. Open the Process Designer desktop editor.
2. Open a process application that contains a business process definition (BPD).
3. In the BPD diagram, click the activity that you want to make conditional.
4. Click the Condition tab in the properties, and then select the Is Conditional
option.Restriction: The conditions tab is disabled for ad hoc activities (unwired
activities). If a wired conditional activity is turned into an ad hoc activity by
deleting wires to and from the activity, the isConditional option becomes
disabled. To set conditions for an ad hoc activity, use preconditions. See
Creating an unstructured (ad hoc) activity
The activity in the BPD diagram includes a diamond-shaped icon to indicate that
it is conditional. The diamond-shaped icon on an ad hoc activity indicates that the
activity has a precondition.
5. Select the conditional activity for execution by using one of the following options:
Option
JavaScript
Description
Enter JavaScript in the
available box. It returns a valid
Boolean (true or false) value.
If the runtime return value of the
supplied script is true, the
activity is carried out. Note: If a
script is present in the box, it
overrides any human decision
at run time to carry out or skip
the activity.
If the Is Conditional option is
enabled and no JavaScript is
entered in the box, the activity
is carried out only if previously
selected. Use the
tw.system.process.selected
ConditionalActivities
75
Description
tw.system.process.conditionalActiv Finds all conditional activities in a
ities
process definition (BPD). Returns a list of
items of the ConditionalActivity
variable type. You can use this property
to construct a Coach that specifies the
conditional activities that you want to run
in the current BPD instance.
tw.system.process.selectedConditio Returns a list of identifiers for the
nalActivities
conditional activities that are to be run at
run time. You can set the value of this
property by providing a list of conditional
activity IDs to be selected. This property
also accepts a comma-separated string
of IDs, which is the output format from
the conditional activity Coach described
earlier.
tw.system.step.isConditionalActivi Determines wheter the current step is a
tySelected
conditional activity that is selected for
execution.
tw.system.process.guid
Returns the ID of the BPD.
tw.system.step.guid
Returns the ID of the step or activity that
is currently running.
76
Procedure
To create an unstructured (ad hoc) activity, complete the following steps.
1. Drag the activity from the palette to your process diagram.Important: Do not add
any input or output wiring to the activity. If you add any wiring to the activity, the
activity is no longer unstructured. The Activity Behavior section is only displayed
for unstructured activities that have User Task, Subprocess, or Linked Process
implementations.
2. Specify the behavior properties of the activity.
A. Select Properties > Implementation > Activity Behavior.
B. Indicate how the activity is started.
- If the activity is started by the system, select Automatically by the process.
- If the activity must be started manually by the user, select Manually by the
user.
C. Indicate whether the activity must be completed.
- If the activity must be completed before the process can complete, select
Yes. The activity is required.
- If the activity does not have to be completed for the process to complete,
select No. The activity is optional.
D. If the activity can be run multiple times, select Repeatable: The activity can
be invoked multiple times.
E. If the activity is started by the system, and must be hidden from users, select
Hidden. This is a background activity that users will not see.
F. If preconditions must be met before the user or system can start the activity,
select There are preconditions that must be met before the activity can be
performed, and specify the conditions that must be met.
1. If there are multiple conditions, use the Match field to select whether all
must evaluate to true, or whether it is sufficient for any one of them to be
true.
2. To specify the conditions by selecting a variable, a comparison operator,
and another variable or literal value, use the default form.
A. Click the variable selection icon to select from a list of variables.
B. In the next field, select the type of comparison that is required, such as
is equal to and not equal to. Tip: The choices that are available depend
on the type of the variable that you selected. For example, for numeric,
date, and time variables, you can also select is less than, is less than
or equal to, is greater than, or is greater than or equal to.
C. In the next field, either enter a literal value or the name of a variable, or
click the other variable selection icon to select from a list of variables.
77
78
Procedure
To start an unstructured (ad hoc) activity, complete the following steps.
1. Retrieve a list of matching unstructured activities and their IDs on a
TWProcessInstance object. On the ActivityListItem object there is a list of
available actions for the current user (the user that executed the
retrieveActivityList() call), as well as the ID of the activity. Refer to the
description of the TWProcessInstance object in JavaScript API for IBM Process
Designer.
- Set the hiddenFilter parameter to retrieve hidden activities.
- Set the checkAuthorization parameter to true to receive only those results
that the current user is authorized to view for the process or case instance.
log.info("querying for piid: " + tw.local.piid);
var pi = tw.system.findProcessInstanceByID(tw.local.piid);
log.info("found process instance: " + pi);
activitiyListProperties.filters = new
tw.object.listOf.ActivityListFilter();
activitiyListProperties.filters.insertIntoList(0, activityListFilter);
79
This feature works only for unstructured activities with a user task implementation.
Refer to the description of the ActivityInstance object in JavaScript API for
IBM Process Designer. log.info("querying for aiid: " + tw.local.aiid);
var ai = tw.system.findActivityInstanceByID(tw.local.aiid);
log.info("starting activity with id: " + tw.local.aiid);
ai.start();
80
Subprocess types
Subprocess is an option for encapsulating logically related steps within a parent
process. Steps in a subprocess can directly access business objects (variables)
from the parent process. No data mapping is required. However, unlike a linked
process, a subprocess can be accessed and instantiated only from the parent BPD,
and it is not reusable by any other process or subprocess.
A subprocess represents a collection of logically related steps contained within a
parent process. You can view a subprocess as a single activity, providing a
simplified, high-level view of the parent process, or you can drill into the subprocess
for a more detailed view of its contents.
A subprocess can be embedded within another subprocess. To drill down into a
collapsed subprocess and view the contents, double-click the subprocess activity in
the parent. To go back to the parent process from within a subprocess or event
subprocess, use the navigation in the upper left corner of the diagram. To return to a
parent process from a linked process, use the menu above the canvas.
Subprocesses can contain swimlanes that are distinct from the parent process. For
example, activities in your subprocess can be carried out by a set of participants that
is different from the set of participants that carry out the activities in the parent
process.
Like other activities, subprocesses can be configured to run multiple times within the
execution of the parent process by configuring looping behavior on the subprocess
activity element in the parent process.
There are three types of subprocesses that you can model in a BPD. Their
characteristics are described in the following table.
Table 1. Types of subprocesses that can be modeled in a business process
definition
Implementation
Description
Characteristics
81
Variable scope
Subprocess
A non-reusable
subprocess that
exists only within
the parent process.
Linked process
A call to another
reusable process.
Each subprocess
must contain at
least one start event
with an
implementation type
of None.Activity
names must be
unique with respect
to the top-level
process activities,
and all other
subprocesses and
event subprocesses
under the same toplevel process.
Inherits variables
from the parent
process and can
contain local private
variables visible
only within the
subprocess.Variabl
e names declared in
a subprocess
cannot be the same
as variable names
declared in any of
its parent
processes. If there
are multiple layers
of embedding, with
subprocesses
contained within
other subprocesses,
variable names
must be unique
throughout the
entire subprocess
hierarchy.
The process called Variable data is
by the linked
local to each
process activity can process, therefore
contain multiple
data mapping is
start events, but
required to pass
must contain at
data into and out of
least one start event the linked process.
with an
implementation type
of None.
82
Event subprocess
A specialized type
of non-reusable
subprocess that is
not part of the
normal sequence
flow of its parent
process, and which
might occur zero or
many times during
the execution of the
parent process.
Must contain a
single start event,
which can be one
of:TimerMessageEr
rorEvent
subprocess
execution can
interrupt parent
process or can run
in parallel.
Activity names must
be unique with
respect to the toplevel process
activities, and all
other subprocesses
and event
subprocesses under
the same top-level
process.
Boundary events
are not supported
on an event
subprocess.
Inherits variables
from the parent
process and can
contain local private
variables visible
only within the
subprocess.Variabl
e names declared in
an event
subprocess cannot
be the same as
variable names
declared in any of
its parent
processes. If there
are multiple layers
of embedding, with
event subprocesses
contained within
other subprocesses,
variable names
must be unique
throughout the
entire subprocess
hierarchy.
83
84
Procedure
1. For a business process, open the parent business process definition (BPD) in the
Process Designer.
A. Drag an activity from the palette onto the diagram area, and enter the name of
the activity in the highlighted box.
B. In the Implementation tab of the Properties view, select Subprocess. The
visualization of the activity in the diagram is updated to reflect the subprocess
activity type.
C. Double-click the subprocess activity to add elements to the subprocess. The
subprocess expands in the editor.
2. For a business process or case type, drag elements from the palette onto the
canvas. By default, your new subprocess contains a start event and an end event.
Subprocesses must contain at least one start event with an implementation type
of None. Names of activities that you create in your subprocess must be different
from the names of activities in the top-level process. The names must also be
different from any subprocess under the same top-level process. For a business
process, swimlanes or phases that you add to your subprocess are independent.
They are not part of the swimlanes and phases that are contained in the parent
business process definition.
3. Like other activities, you can configure your subprocess to run the subprocess
steps multiple times. Select the subprocess activity in the parent process and set
the repeating behavior in the General tab.
4. Subprocesses have access to all of the variables that are defined in the parent
process. You do not need to map data to pass data into or out of the subprocess.
However, you can Modeling subprocess data that are only available to the
subprocess (and any subprocesses it contains).
What to do next
In a business process, to return to the parent business process definition, use the
85
86
Procedure
1. Open the parent business process definition (BPD) in the Process Designer.
2. Drag an activity from the palette onto the diagram area, and type the name of the
activity in the highlighted box.
3. In the Implementation tab of the Properties view, select Linked Process. The
visualization of the activity in the diagram is updated to reflect the Linked Process
activity type.
4. Specify another process to call during the execution of your process.
- To select an existing process, click Select, and choose the business process
definition.
- To create a reusable process:
A. Click New.
B. Enter a name for the new process and click Finish. In the editor, continue to
specify this new process definition, or return to the parent process.
- You can also Calling a linked process dynamically by using a variable defined in
the parent process.
5. In the parent process, connect the linked process activity to other elements in the
process flow.
6. Variables in a linked process activity are local to the linked process. If you want to
pass data into or out of a linked process activity, you must map the inputs and
outputs of your linked process to the inputs and outputs of the linked process
activity in the parent. Complete one of the following steps in the Data Mapping
tab of the Properties view for the linked process activity:
- If you declared variables in the parent process that have the same names and
data types as the input and output variables in the linked process, use auto-
87
88
Procedure
1.
2.
3.
4.
5.
89
90
Message
Timer
if a requested item cannot be located within a certain amount of time, the out-ofstock subprocess can be triggered by a timer start event.
- An error start event might be triggered when something goes wrong in the process,
for example, the order fulfilment system is non-responsive. Error start events can
be triggered only from within the parent BPD or its subprocesses.
A parent process cannot complete until all active event subprocesses are complete,
unless the parent is terminated by a terminate end event. A terminate end event in
an event subprocess terminates only the activities that are contained within that
event subprocess.
Boundary events cannot be attached to event subprocesses. To handle exceptions
within an event subprocess, for example, errors that arise during the event
subprocess execution, event subprocesses can themselves contain event
subprocesses.
To add an event subprocess to your BPD:
Procedure
1. Open the parent business process definition (BPD) in the Process Designer.
2. Drag an activity from the palette onto the diagram area, and type the name of the
activity in the highlighted box.
3. In the Implementation tab of the Properties view, select Event Subprocess. The
visualization of the activity in the diagram is updated to reflect the event
subprocess activity type. By default, new event subprocesses are assigned an
error start event.
4. To change the start event type and properties and to add activities to the event
subprocess, double-click the event subprocess activity to expand it.
5. Select the start event and, from the Implementation tab in the properties view,
select a new implementation type from the list.
6. The start events for event subprocesses can be interrupting or non-interrupting.
When triggered, event subprocesses with an interrupting start event terminate all
activities in the parent process. Activities in an event subprocess with a noninterrupting start event run in parallel with the parent process. You can specify
whether the start event of the event subprocess is interrupting or non-interrupting
by selecting or by clearing Interrupt Parent Process. Note: Error start events in
an event subprocess always interrupt the parent process and cannot be set to
non-interrupting.
7. To configure an event subprocess to be repeatable, select Repeatable? on the
Implementation tab. When you select this property, the event subprocess might
run several times during the execution of a process, and might have multiple
instances that run in parallel.Note: Unlike subprocesses, looping behavior is not
supported for event subprocesses.
8. Drag elements from the palette onto the canvas. The names of the activities that
you create in your subprocess must be different from the names of the activities in
the top-level process or any other subprocess or event subprocess under the
same top-level process. Any swimlanes or phases that you add to your
subprocess are independent from the swimlanes and phases that are contained
in the parent BPD.
92
9. Like subprocesses, event subprocesses have access to the data of the parent
process. Data mapping is not required to pass data into or out of the event
subprocess. You can also declare private variables within the event subprocess
itself, which are not visible to the parent BPD. See Modeling subprocess data.
What to do next
To return to the parent BPD, use the navigation in the upper left of the canvas.
Parent topic:Subprocess types
93
Procedure
1. Open the Process Designer desktop editor.
2. Open a process application in the Designer view.
3. Click the plus sign next to Data and select User Attribute Definition from the list
of components.
4. In the New User Attribute Definition window, provide a unique name for the
attribute, and click Finish.
94
5. Supply the following requested information about the user attribute definition:
Table 1. Input required for the user attribute definition
Dialog area
Common
Field or link
Name
Documentation
Type
Business Object
Source
Source
Description
Displays the name that
you provided in step 2.
(Optional) Provides a
description of the attribute
in this field.
Specifies the business
object type. The default
type is String. Click
Select to specify a
different type. Click New if
you want to define a new
business object.
Specifies the source of the
current value. The source
is IBM Business Process
Manager.
Specifies the sources of
other possible values for
the user attribute. Select
the source from the list,
Any Allowed, or List. The
choice that you make
determines the
information that is
required.
Specifies that the possible
values for the attribute are
limited only by its
business object type.
Enter each possible value
in the Value field and click
Add. You can remove
values from the list by
clicking Remove or
change the order of the
values that are displayed
by clicking Up and Down.
6. Click Save on the main toolbar.IBM Process Designer saves the user attribute
definition, and you can use the attribute when creating teams.
Parent topic:Creating a business process definition (BPD)
95
Validating processes
Use validation functions to refine process definitions as you build them.
The Designer in Process Designer includes validation functions that alert you to
issues in your process applications and toolkits. Validation provides feedback about
the following types of issues:
- Broken references, such as missing implementations for activities
- Problems with parameter mappings
- Duplicate names and other naming violations
If IBM Business Process Manager Designer detects issues, the Validation errors
category in the library displays the number of errors detected. You can click the
category to display a list of issues.
Double-click an item in the list to open the item, and then click the Validation Errors
tab to list each error for the selected item.
Parent topic:Creating a business process definition (BPD)
96
Task types
Learn more about the task types that are available when modeling with IBM
Process Designer.
IBM BPM supports the following task types:
Table 1. Available task types
Task type
User Task
Description
User tasks must be completed by
process participants and are associated
with Human services by default. When
you drag a Human service from the
library to a BPD diagram, Process
Designer automatically creates an
activity with a User task with the Human
service selected. When you drag an
activity from the palette to a participant
lane in a BPD diagram, Process
Designer automatically creates an
activity with a User task with the Default
Human service selected. For cases
where you want a user to start the
service but no additional user
involvement is required, you can also
choose a user task type and associate a
service with it, such as an Integration or
Advanced Integration service. In this
way, Process Designer automatically
creates the required user implementation
that you need when you drag process
components onto a diagram. You can
also choose User Task and an
associated service for an activity
implementation, as described in
Implementing activities in a BPD.
97
System Task
Script
Decision Task
Note: Simple and multi-instance loop properties can be defined for all task types.
For more information, see Creating loops for a BPD activity.
Parent topic:Creating a business process definition (BPD)
98
99
Procedure
To create a process instance user interface, first create a client-side human service,
then create your customized interface by modifying the generated service and
adding a coach.
1. Open the BPD for which you want to create the user interface.
2. Switch to the Views page.
3. Under Details UI, select the interface that you want to create (Default or
Instance Owners).
4. Select a client-side human service, or create a new one. IBM BPM provides a
template in the Dashboards toolkit, called Instance Details UI Services Template.
You can copy this template and modify it to create your custom UI. The template
contains the following coaches:
- View Instance Details coach, which contains the following coach controls:
- Default Instance Details Template
- displays the instance details in Process Portal
- Data section
- displays the values of the variables that are passed into the client-side
human service.
- Show error, which returns an error if the instance is not found.
For more information, see Instance Details UI Service template.
100
101
Building services
Use services to implement the activities in a business process definition (BPD).
When a BPD starts and the tasks within it are invoked, services perform the required
functions.
The type of service that you choose to create depends upon the requirements of the
activity. For example, if an activity requires integration with an external system, such
as a database, you can create an integration service. If an activity requires that call
center personnel enter data about customer requests, you can create a human
service with a coach.
- Service types
Learn about the types of services available in IBM BPM and when to use each
type.
- Service components
Learn about the tools and components available when building services in IBM
Process Designer.
- Building a Decision service
Build a Decision service when you want a decision or condition in a business rule
to determine which process implementation is invoked. For example, when a
certain condition evaluates to true, Process Designer implements the associated
activity or action.
- Building a client-side human service
Build a client-side human service to handle the interaction for process or case
instances between the system and users through interactive tasks, dashboards, or
user interfaces. Within a client-side human service, you can use coaches, clientside scripts, and services to create a service flow that is run entirely in a web
browser.Case management functions are only available if you have IBM BPM
Advanced with the Basic Case Management feature installed.
- Building a heritage human service
Build a heritage human service when you want an activity in your business
process definition (BPD) to create an interactive task that process participants can
perform in a web-based user interface.
- Building an Ajax service
Build an Ajax service when you want a coach view to send data to or retrieve data
from the server asynchronously, such as for auto-completion in text fields, for
default selection values in selection lists, and so forth.
- Building an integration service
Build an integration service when you want a flow to interact with an external
system.
- Building an advanced integration service
An advanced integration service is used to call a service implemented in IBM
Integration Designer from a business process definition (BPD) (via a system task)
or another service (via a nested service).
- Building a General System service
Use General System services when you want to orchestrate other background
services, manipulate variable data, generate HTML for a Coach, or perform some
102
103
Service types
Learn about the types of services available in IBM BPM and when to use each
type.
The type of service that you choose to create depends upon the requirements of the
activity. For example, if an activity requires integration with an external system, such
as a database, you can create an integration service. If an activity requires that call
center personnel enter data about customer requests, you can create a client-side
human service with a coach.
The following table describes the types of services available in IBM BPM:
Table 1. Types of services available in IBM BPM
Service type
Heritage human service
Description
Use a heritage human
service to implement an
interactive task in a
business process definition
(BPD) or a dashboard that
users can use in a webbased application such as
IBM Process Portal.
Heritage human services
run on the server and
supply user interfaces to a
web browser. Heritage
human services are
authored in the Process
Designer desktop editor,
and can contain coaches,
heritage coaches, and
postpones. A heritage
human service is the only
type of service that can call
other heritage human
services.
104
See...
Building a heritage human
serviceDifference between
client-side human services
and heritage human
services
105
Decision service
Integration service
Advanced integration
service
106
Building an Integration
service
Building an Advanced
Integration service
107
Service components
Learn about the tools and components available when building services in IBM
Process Designer.
When developing a service diagram in the Designer view in IBM Process Designer,
the following tools and components are available from the palette. Not all tools and
components are available for each type of service.
- All service types
- Integration service
- Heritage human service
- Decision service
- IBM Case Manager Integration service
Description
Enables you to select and move
components on the diagram.
Enables you to connect service
components to establish the order in
which the steps in the service occur.
Use when you want to write JavaScript to
run on the Process Server in the service
context. The Server Script component is
useful for parsing through variables and
executing programmatic commands.
Use to bind blocks of formatted text (for
example, HTML, XML, or XSLT) directly
to a service variable. This eliminates the
need to store large blocks of text in
default values for variables.
Use to model a point in the process
execution where only one of several
paths can be followed, depending on a
condition.
Use to end service execution. For
services that contain multiple paths, each
path requires its own end event. Note:
An end event is automatically included
each time you create a service.
Use to add information about the overall
service or each step in the service to the
diagram. Adding notes helps other
developers understand your design.
108
Integration service
The following tools and components are available from the palette for Integration
services only:Table 2. Tools and components available from the palette for
Integration services only
Component icon
Description
Use to run an external web service. This
component enables you to supply a
WSDL URI and then use any of the
available services.
109
Description
Use to implement the interfaces for your
heritage human services so that users
can participate in a business process.
For more information, see Building
coaches. The coach tool is shared with
the client-side human services. For more
information, see Tools available from the
palette for client-side human services.
Use to implement the interfaces for your
heritage human services so that users
can participate in a business process.
For more information, see Building
heritage coaches. This component is
used for heritage human services only.
Use to change the priority, due date,
status, or other aspects of a task.
Use to halt processing without changing
the status of a task. This component is
used for heritage human services only.
Decision service
The following tools and components are available from the palette for Decision
services only:Table 4. Tools and components available from the palette for Decision
services only
Component icon
Description
Use to build conditions for your Decision
services.
Use to include decision services
available on an ILOG JRules Rule
Execution Server.
110
Description
Use to integrate a case management
case in IBM Case Manager.
111
112
The following topics describe how to author, implement and manage business rules
in Process Designer.
- Scenario: Creating a Decision service in a Personalized Notification process
This scenario shows you how to create, configure and test Business Action
Language (BAL) rules in a Decision service. The scenario presents a sample
business process that is used by a bank to notify a customer when a payment is
made from a specific account.
- Adding a Decision service to a process
You can add a Decision service to a business process definition (BPD). Use a
Decision service when you want a decision or condition to determine which
process implementation is invoked. For example, when a certain condition
evaluates to true, IBM Process Designer implements the associated activity or
action.
- Implementing an activity using a Decision service
You can implement an activity using a Decision service.
- Attaching a Decision service to a decision gateway
You can use a decision gateway in your business process definition (BPD) when
you need to model a point in the process execution where only one of several
paths can be followed, depending on a condition. You can also attach a Decision
service to a decision gateway.
- Adding a BAL Rule component to a service
The Business Action Language (BAL) Rule component provides a rule editor that
allows rule designers to author business rules using natural language technology.
Using natural language, instead of JavaScript, to author rules means that no
programming expertise is required to create business rules, and the rules are
easier for people to read and understand.
- Adding and modifying Decision service variables
Each IBM Business Process Manager Decision service has a set of input, output,
and private variables that are declared for that service. The business terms and
phrases that you define as variables are available for you to use when you are
writing rules. For example, the variable appear in the Content Assist menu in the
rule editor.
- Testing a Decision service
When you have finished creating a Decision service and authoring rules in a rule
component, such as a BAL Rule component, you can test the Decision service to
determine if the rules are being applied as you intended. If an error or exception
occurs within a rule, you will see messages about the error during testing, and you
can debug the specific rule component or rule that caused the error.
- Scenario: Exporting rules to a Rule Execution Server
This scenario shows you how to export, migrate and connect BAL rules to a rule
execution server (RES). You can migrate the rules that you created in Process
Designer to a business rules management system (BRMS) such as IBM
WebSphere ILOG JRules, and then continue to use the rules in a business
process definition.
- Exporting rules for use in Rule Studio
You can export a set of rules to create a project file that you can then import and
113
114
Procedure
To add a Decision service to the Personalized Notification process, complete these
steps:
1. Open the Process Designer desktop editor.
2. Open a process application that contains a business process definition (BPD).
3. Create a new Decision service called NotificationRulesService.
A. In the Library panel on the left side of the Process Designer window, move the
mouse cursor over the Decisions item in the list of library items for the
process application.
B. Click the plus sign next to Decisions to add a new Decision service.
C. In the Create New window, click Decision Service.
D. In the New Decision Service window, enter NotificationRulesService as the
Decision service name, then click Finish.
115
You can find more information about adding a Decision service in the related
topic "Adding a Decision service to a process."
4. Add a BAL Rule component called AlertRules to the NotificationRulesService
Decision service.
A. Make sure that you are editing the NotificationRulesService Decision service.
B. Click BAL Rule in the component palette and drag the BAL Rule component
icon from the palette to the service diagram.
C. In the Properties tab, enter AlertRules ad the name for the new BAL Rule
component.
D. Click Save, or use the Ctrl+S keyboard shortcut to save the Decision service.
You can find more information about adding a BAL rule component in the related
topic "Adding a BAL Rule component to a service."
5. Create a business object called CheckingAccount that contains parameters
such as CustomerName, Balance and Payments.
A. Add a business object from the Process Designer library panel.
1. Click the indicator next to the process application name in the library panel
to see the categories of library items in the current process application.
2. Click the plus sign next to the Data library item.
3. In the Create New window, click Business Object.
4. In the New Business Object window, enter CheckingAccount as the
name for the business object, then click Finish.
B. In the Behavior section of the Business Object panel, select Complex
Structure Type as the Definition Type.
C. Add parameters to the CheckingAccount business object.
1. In the Parameters section of the Business Object panel, click Add.
2. In the Parameter Properties section, add the CustomerName parameter
with the variable type set to String, the Balance parameter with the variable
type set to Decimal, and the PastPayment parameter with the variable type
set to Payment.
D. Click Save, or use the Ctrl+S keyboard shortcut to save the Decision service.
116
You can find more information about creating a business object in the related
topic "Adding variable types and business objects to a Decision service."
6. Define which of the parameters are used as input variables to the Decision
service, such as CustomerName, Balance and PastPayment, and which
parameters are output variables from the Decision service, including the
notification message.
A. Make sure you are editing the NotificationRulesService Decision service.
B. Click the Variables tab.
C. Click Add Input to add the input variables:
1. In the Details section, enter accountIn as the name for the input variable.
2. Click Select next to Variable type and click CheckingAccount in the list.
3. Click the plus sign next to accountIn in the Variables list to confirm that
CustomerName, Balance and PastPayment are included in the list.
D. Click Add Output to add the output variable, notificationOut.
1. In the Details section, enter notificationOut as the name for the output
variable.
2. Click Select next to Variable type and click Notification in the list.
3. Click the plus sign next to notificationOut in the Variables list to confirm
that message is included in the list.
E. Click Save, or use the Ctrl+S keyboard shortcut to save the Decision service.
117
You can find more information about defining Decision service variables in the
related topic "Adding and modifying Decision service variables."
7. Use the BAL Rule editor to create rules in the AlertRules BAL Rule component.
A. Make sure you are editing the NotificationRulesService Decision service.
B. Click the Diagram tab, then click to select the AlertRules BAL Rule component.
C. Click the Decisions tab. By default, the rule editor opens with an empty BAL
rule window. The rule window contains a basic template for a simple rule, with
one condition (if) and one action (then).
D. Click inside the rule window to begin creating a new rule from the template.
1. Click the condition placeholder, next to if, to use the Content Assist menu to
complete the condition. Add the following condition statements by doubleclicking on each as it appears in the list. If the list closes before you can
select a condition statement, press Shift+Spacebar to reopen the Content
Assist menu.
- if the amount of
- paymentIn
- is more than
- the balance of
- accountIn
The first part of the rule (if) looks like this:if the amount of paymentIn is more than the balance
of accountIn
E. Click the action placeholder next to then and add the following condition
statements.
- set the message of
- notificationOut
- to
- string
When you double-click to select string, the edit cursor appears between two
double quotation marks. Type the notification message, Payment takes
account overdrawn between the double quotation marks.The second part of
118
F. Add a second rule editor window. Click the plus sign in the upper right corner
of the BAL rule editor panel. Repeat the previous sequence of steps to create
a second rule that looks like this:if there is no payment in the past payments of accountIn
where the payee of this payment is the payee of paymentIn ,
then
set the message of notificationOut to the message of notificationOut + "\n" +
"Payment to new payee: " + the payee of paymentIn ;
G. Click Save, or use the Ctrl+S keyboard shortcut to save the Decision service.
You can find more information about using the BAL Rule editor in the related
topic "Creating a rule using the rule editor."
8. Attach the NotificationRulesService Decision service to the Send Alert decision
gateway.
A. Make sure you are editing the NotificationRulesService Decision service.
B. In the business process definition diagram, click the Send Alert decision
gateway icon to select the decision gateway.
C. Click the Properties tab.
D. Click Decision.
E. In the Decision Service section, click Select. Click to select the
NotificationRulesService Decision service.
F. Click Implementation in the Properties tab.
G. Under the Decisions heading, add a variable statement to each decision to
control the output of the decision gateway.
A. Make sure that you are editing the NotificationRulesService Decision service
and the AlertRules BAL Rule component.
B. In the NotificationRulesService Decision service, click to select the Send Alert
decision gateway.
C. Set a breakpoint for the gateway. Set breakpoints at specific locations in the
process where you want the process flow to pause during testing so that you
can determine the status of the process, and identify any errors that might
have occurred.
D. In the AlertRules BAL Rule component panel, click the Debug
icon in the
banner above the rule editor windows.
What to do next
When you have finished creating, configuring and testing the AlertRules BAL rules in
the NotificationRulesService Decision service, then you have completed the
scenario procedures. If you want to refine or share the rules that you create in
Process Designer, you can export the rules into a project file and import them into
IBM WebSphere ILOG JRules. For more information, refer to the related topic
"Exporting, migrating and connecting BAL rules to a rule server."
Parent topic:Building a Decision service
Related information:
Adding a Decision service to a process
Adding a BAL Rule component to a service
Adding variable types and business objects to a Decision service
Adding and modifying Decision service variables
120
121
Procedure
1. Open the Process Designer desktop editor.
2. Open a process application that contains a BPD.
3. Create a new Decision service.
A. Click the plus sign next to Decisions to add a new Decision service.
B. In the Create New window, click Decision Service.
C. In the New Decision Service window, enter a name for the new Decision
service, then click Finish.
D. Process Designer displays the diagram of the service with the default Start
Event and End Event components.
4. Drag a rule component, such as a BAL Rule, JRules Decision Service or Decision
Table component, from the component palette to the Decision service diagram.
5. Depending on which component or components you added to the service
diagram, follow the additional steps in the following related topics to configure the
components in the Decision service:
- Adding a BAL Rule component to a service
- Adding a JRules Decision Service component to a service
- Adding a Decision Table component to a service
What to do next
You can now nest this Decision service in any other service within your process
application that requires this logic. Be sure to adjust the input and output variables
as required for each implementation. See Declaring and passing variables for more
information.
122
123
Procedure
To select a Decision service as the implementation for an activity, complete the
following steps:
1. Open the Process Designer desktop editor.
2. Open a process application that contains a business process definition (BPD).
3. Open the BPD diagram that contains that activity that you want to implement
using a Decision service.
4. Click the activity in the diagram to select the activity.
5. Click the Implementation option in the properties.
6. Click the drop-down list and select Decision Task from the available options.
7. Click the Select button to choose the Decision service that you want from the
library. If the service does not yet exist, click the New button to create it.
Parent topic:Building a Decision service
124
Procedure
To attach a Decision service to a decision gateway, complete the following steps:
1. Open the Process Designer desktop editor.
2. Open a process application that contains a business process definition (BPD).
3. In the BPD diagram, click the decision gateway icon to select the decision
gateway where you want to attach the Decision service.
4. Click the Properties tab.
5. Click Decision.
6. In the Decision Service section, click Select.
7. Select the Decision service you want to attach to the gateway from the list of
available services.
8. If you decide not to use an existing Decision service, you can create a new
service. Click New next to the Service field. You can remove an attached
Decision service from a decision gateway. Click the delete icon (X) next to the
Decision service name.
9. The Inputs section contains a variable condition statement field that controls the
behavior of the gateway, based on the result of the rules in the rule component.
A. To select an input variable statement, click the variable icon
to display a
list of available variables.
B. The Inputs section includes an auto-map function. To create a mapping
between the variables used in the Decision service and the variables that are
used in the main business process definition, click the auto-map icon
.
When developing processes in IBM Business Process Manager, you must set
the input and output mapping for each activity included in a business process
definition so that the variable values received and generated by services map
to the variables from the main process definition. For more information about
the auto-map function, refer to the related topic "Mapping input and output
data for an activity."
125
The text field under the Inputs heading shows the JavaScript object that
represents the variable. The variable name is displayed to the right of the Inputs
field.
10. Click Implementation in the Properties tab.
11. Under the Decisions heading, add a variable statement to each decision to
control the output of the decision gateway. The last decision is the default
condition sequence line, which is followed if none of the decisions evaluate to
true. You can change the position of a decision. Click the down arrow or the up
arrow next to a decision to move it down or up in the decision list.
12. For each decision above the last (default) decision, add an output variable
statement. Click the variable icon to display a list of available output variables
that are defined in the Decision service. The text field for each decision shows
the JavaScript object that represents the variable condition.
13. To enable the process to process the decision and choose the correct output
sequence line for the decision gateway, you must also specify a comparison
function and a value for each decision. For example, if the purpose of the
decision gateway is to determine whether a notification message is sent to a
customer or not, then the decisions are No Notification (the process ends with
no message sent), or Send Notification. The value of the No Notification decision
is null, because the rules in the decision service have determined that no
notification message is required. The value of the Send Notification decision is
determined by variables that are defined in the rules. In this example, Send
Notification is the default decision. The example decisions are illustrated in the
following figure:
In this screen capture, the input variable tw.local.notification.message in
the top position is set to no message as output; that is, no text will be sent as
indicated by the quotation marks with no text inside (""). This output would be
determined by the logic of the decision service. Under a certain set of conditions,
no message would be sent. For example, if the decision service checked a
database and found that the customer no longer existed it would not send a
message. Another possibility might be that the customer had an invalid email
address, so no message would be sent.The input variable and its output in the
bottom position are hidden in this screen capture; however, by using the arrows
you could move the bottom position up to the top position and the code would be
displayed. This is the default output, which is to send a message. The message
sent as output could be in quotation marks, for example, "Your order is
confirmed," or the message sent as output might be in an another variable such
as orderConfirmationNumber, which would contain the order number for
something the customer had ordered.
Parent topic:Building a Decision service
Related information:
Mapping input and output data for an activity or step
126
127
Procedure
1. Open the process application in the Designer view.
2. Create a Decision service.
3. In the diagram of the new Decision service, click BAL Rule in the component
palette and drag the BAL Rule component icon from the palette to the service
128
diagram.
4. In the Properties tab, enter a name for the new BAL Rule component, such as
ExpenseApproval.
5. Click the Variables tab.
6. Click Add Private to add a private variable to the Decision service. For this
sample Decision service, add the private variable, request.
A. Replace Untitled1 in the Name field with request .
B. Click Select next to Variable Type and select the type from the list.
7. If you use the Activity Wizard to create a Decision service, you can choose
existing variables to add as input and output. You should use the Activity Wizard
when you start with an existing activity and want to quickly create a service to
implement the activity. To access the wizard, right-click an activity icon in a
process diagram and select Activity Wizard from the list of options.
8. Click Add Private.
9. Replace Untitled1 in the Name field with approvalRequired .
10. Click Select next to Variable Type and select the Boolean type from the list. The
Boolean variable type is included in the IBM BPM System Data toolkit. The
System Data toolkit is included in each process application by default.
11. Click the Decisions tab to open the rules editor.
What to do next
Create a rule that is implemented for this Decision service. Refer to the related topic
"Authoring rules using the BAL rule editor."
- Creating rules using the rule editor
You can create rules using the Business Action Language (BAL) rule editor. The
rule editor uses natural language technology to express business decisions in a
form that is readable by humans but can also be run by a rule service runtime such
as the JRules Rule Execution Server.
- Business rule parts and structure
Business rules, such as action rules or decision tables, express business policy
statements using a predefined business vocabulary that can be interpreted by a
computer. Rules authored in the Business Action Language (BAL) are also easily
readable by humans.
- Defining variables in the rule editor
Variables are defined in the definitions part of a business rule.
- Copying and pasting content in the rule editor
You can copy content from a rule to the system clipboard, or paste content written
outside the rule editor into the editor window.
- Setting the rule language
You can use the locale preference setting provided in IBM Process Designer to
set the language used in a BAL Rule component.
- Troubleshooting BAL rule editor errors
The Business Action Language (BAL) rule editor highlights errors with red
underline in the editing window.
Parent topic:Building a Decision service
Related information:
129
130
Procedure
1. Make sure you are working in the sample Decision service that was created in the
related topic "Adding a BAL Rule component to a service."
2. Click the Decisions tab to open the rule editor.
3. By default, the rule editor opens with an empty BAL rule window. The rule window
contains a basic template for a simple rule, with one condition (if) and one action (
then).
4. Click inside the rule window to begin creating a new rule from the template.
A. Click the condition placeholder, next to if, to use the Content Assist menu to
complete the condition. Double-click a condition statement in the menu to add
that condition to the rule.
- If the list of conditions is long, you can use the Tree Completer menu instead
of the Content Assist menu to select the condition statement. With the edit
cursor on the <condition> placeholder, press Ctrl+Shift+Spacebar to open
the Tree Completer menu.
- If you know the name of the condition you want to insert, start typing the
condition name. The Tree Completer shows all the conditions that match the
name as you type, as shown in the following diagram:
131
B. Click the action placeholder, next to then, to select from the menu of possible
actions. Double-click an action statement in the menu to add that action to the
rule. For more information about using the menu to select actions, refer to the
related topic in the IBM WebSphere ILOG JRules InfoCenter, "Inserting a term
or a phrase."
5. To add additional rule parts to the rule, click to place the editor cursor above or
below the existing rule content, then press Ctrl+Spacebar to activate the Content
Assist menu. The Content Assist box displays a list of valid rule parts. For
example, to create a definition rule part, click before the if condition section, then
press Ctrl+Spacebar to open the Content Assist menu and select definitions. To
create an else rule part, click below the then section of the rule.
6. To add additional rules to the BAL Rule component, click the plus symbol at the
top of the rule editor window. Each time you click the plus symbol, a rule editor
window is opened. Each window contains the simple rule template.
7. In a BAL Rule component that contains multiple rules, you can change the order
of the rules. Click the up arrow beside the editing window to move the rule up one
place in the rule order. Click the down arrow to move the rule down one place in
the rule order.
8. The rule editor saves the rules periodically as you are authoring. To save all the
rules in the BAL Rule component while you are authoring, click Ctrl+S, or click
the Save icon in the Process Designer action bar.
9. To exit the rule editor, click the exit icon (X) next to the Decision service name.
Parent topic:Adding a BAL Rule component to a service
Related information:
Business rule parts and structure
Adding a BAL Rule component to a service
Inserting a term or a phrase
132
- refuse the loan with the message "Credit score below" + minimum_score;
The parts must be defined in the following order:
1. definitions part
2. if (conditions) part
3. then (actions) part
4. else (optional actions) part
Definitions
The definitions part of a rule gives you more control over your business rules when
you set variables at the beginning of your rule. Variables help you identify and then
reference an occurrence of a business term by a convenient name. Use variables to
make your business rules less ambiguous and easier to understand.
Define a variable by giving it a name of your choice and then setting a value for the
variable. This value can be a number (or an arithmetic expression whose result is a
number), text, or a predefined business term that already exists in your rule (for
example, customer). Once you have set a variable, it becomes available in all the
parts of the current rule. The variable is valid only in the rule in which it is defined.
The simplest use of definitions is to define a constant value that you can use
throughout your rule. For example, by declaring a variable called minimum_score in
the example rule, you make the rule easier to understand:
- definitions
Conditions
The condition part of a rule specifies under what conditions the actions in the action
part of the rule will be carried out. Conditions are represented in the rule editor by
133
the text (or number) that appears after if, ending at then. The word then signals the
beginning of the action part of the rule.In the example rule, the condition is defined
so that when the credit score of the borrower is below the minimum value, then the
loan to the customer is refused.
- if
Actions
The action part of a rule describes what to do when the conditions of the rule are
met. Actions are represented in the rule editor by the text that appears after then
and else. If there is more than one action to perform, the actions are carried out in
the order that they appear in the action part of the rule.In the example rule, the
action is defined so that when the condition evaluates to true, then the resulting
action is to refuse the loan, and issue a message "Credit score below 200."
- then
- refuse the loan with the message "Credit score below" + minimum_score;
Optionally, you can include an else part in a rule. The else part of a rule is an
optional block of actions that specify what to do when the conditions are not met.
You can use an else rule part in combination with variables in the definitions part to
control the rule action more precisely. If a rule contains both definitions and a
condition part, the else part of a rule will only be run if the conditions set in the
variables are satisfied and the condition part of the rule is not satisfied. This sample
rule shows this application for the else part:
- definitions
- apply a 5% discount;
This rule applies an extra discount only for customers who qualify for the Gold
category. For more information about actions, refer to the section "Understanding
your rules -- Actions" in the WebSphere ILOG JRules InfoCenter.
135
Procedure
To define a variable, complete these steps:
1. In the definitions part of the rule, press Ctrl+Spacebar, and double-click to select
set from the Content Assist menu. The content of the Content Assist menu
changes to show the default name for new variables, variable1. After the
definitions are specified, the Content Assist menu changes to show the closing
semicolon.
2. Double-click in the Content Assist menu to insert the placeholder variable name
variable1 in the rule.
3. Type over the placeholder variable name to replace variable1 with the name of
your variable. If your variable is only one word, quotation marks are not required.
If your variable is a phrase containing more than one word, you must put the
phrase between quotation marks.
4. Press Ctrl+Spacebar, and select a variable type from the menu. In IBM BPM,
every variable name is associated with a variable type, which determines what
values are legal for the associated variable. For more information, refer to the
related topic "Variable types."
5. After the variable type is specified, the Content Assist menu changes to show the
closing semicolon, or the optional building blocks from, in, and where. If you have
finished defining the variable, select the closing semicolon. To define a variable
using the optional building blocks, continue by selecting from, in, or where.
6. The variable definition ends with the closing semicolon. Once a variable is
defined, you can use the variable in all parts of the business rule.
Example
To make a rule easier to read, you can use a variable to define a one-to-one
relationship between business objects. In the following business rule, the variable
the shopping cart is defined using the one-to-one relationship between two objects:
the ShoppingCart and the Customer:
- definitions
136
- if
What to do next
You must initialize complex variable structures before running the Decision service.
In IBM BPM, all complex variables and all lists (arrays) must be initialized before
you use them in a BPD or service. If you do not initialize a complex variable or list,
you may receive runtime errors or notice that the controls to which the variables are
bound do not behave as expected. For more information, refer to the related topic,
"Initializing complex variables and lists."
137
Procedure
To cut or paste content in the rule editor, complete the following steps:
1. You can copy the contents of an individual rule to the system clipboard.
A. Click to place the edit cursor inside the rule that contains the rule content you
want to copy.
B. Highlight the content you want to copy. To select the entire content of the rule,
press Ctrl+A.
C. Copy the content to the clipboard using a keyboard shortcut, or the product
menu, or the right-click menu, as described in the following steps:
1. Press the copy keyboard shortcut for your system. For example, on a
Microsoft Windows system, the copy function shortcut is Ctrl+C.
2. From the main product menu, click Edit > Copy.
3. Right-click in the rule editor window and select Copy from the menu.
2. To paste content from the system clipboard into a rule, complete these steps.
A. Make sure that the content you want to paste into the rule has been copied into
your system clipboard.
B. Click to place the edit cursor inside the rule in the location where you want the
pasted content to appear.
C. Paste the content to the rule editor window using a keyboard shortcut, or the
product menu, or the right-click menu, as described in the following steps:
1. Press the paste keyboard shortcut for your system. For example, on a
Microsoft Windows system, the paste function shortcut is Ctrl+V.
2. From the main product menu, click Edit > Paste.
3. Right-click in the rule editor window and select Paste from the menu.
Parent topic:Adding a BAL Rule component to a service
138
Procedure
To change the locale setting, complete the following steps:
1. From the main menu, click File > Preferences
2. Click IBM BPM to display the available options.
3. Click Rules.
4. Click English next to BAL Decision Locale, then select a language from the
menu.
Parent topic:Adding a BAL Rule component to a service
139
2. Click the light bulb icon or move your cursor to the error in the rule, and press
Ctrl+1 to open the Quick Fix message.
141
Procedure
To add or modify variables for a Decision service, complete the following steps:
1. Open the Process Designer desktop editor.
2. Open a process application that contains a business process definition (BPD) in
the Designer view.
3. Make sure you have selected the Decision service where you want to add or
modify variables.
4. Click the Variables tab.
5. Existing variables are organized into three sections: Input, Output, and Private, as
shown in the following example. Click the plus sign next to a section to see the
variables in that section.
142
6. You can add a variable to the Decision service by completing one of the following
steps:
- Click Add Input to add a variable that you can use for input into a rule.
- Click Add Output to add a variable that you can use for output from the rule.
- Click Add Private to add a variable that applied only to the current Decision
service.
The following information applies to variables:
- Variables are mapped to the IN, OUT or IN-OUT parameter directions
automatically, depending on how the variable is used in the rule. For example, a
variable that is referenced in a rule but is not updated at run time is identified as
an IN variable. For more information about parameters, refer to the related topic
"Adding variable types and business objects to a Decision service."
- The input or output designation for variables might affect the way the Decision
service runs, but the designation is not significant when you are authoring BAL
rules because input, output and private variables are all referenced identically in
a BAL rule.
- If you create an input and an output variable that have the same name, only one
variable is actually created. The variable is used for both input and output at the
Decision service level.
- Exposed Process Variables (EPVs) are managed at the process application
level, and allow the IBM Business Process Manager administrator to specify
designated users who can set or alter variable values using the Process Admin
Console while instances of a process are running. The Decision service can pick
up an EPV variable that has been created in a process application and use the
variable in a rule to affect the way that the Decision service runs. For more
information about EPVs, refer to the related topic "Creating exposed process
values."
143
7. You can modify or view the properties of an existing variable. Click to highlight the
variable name, then modify the variable properties under the Details section, or
view the Default Value of the variable if a default value has been defined, as
shown in the following example:
What to do next
You must initialize private variables before running the Decision service. In IBM
BPM, all private variables must be initialized before you use them in a business
process definition or Decision service. If you do not initialize a variable, you may
receive runtime errors or notice that the controls to which the variable is bound do
not behave as expected. For more information, refer to the related topic, "Initializing
complex variables and lists."
- Default rule variables and parameters
Pre-defined variables and variable types are deployed from the System Data
toolkit when IBM Business Process Manager is installed.
- Adding variable types and business objects to a Decision service
In IBM Business Process Manager, you can create a custom business object
(variable type) for the Decision service. The variable type becomes part of the data
for the process application, and is available for all business process definitions
(BPDs) and services included in the process application.
144
- Variable types
You can define a Decision service variable by first specifying the name of the
variable, then setting the variable type. The variable value can be a simple data
type such as a string, integer, or date. You can also define a complex variable type
using a business object that contains parameters.
Parent topic:Building a Decision service
Related information:
Adding variable types and business objects to a Decision service
Creating exposed process values (EPVs)
145
The following variable types are not supported for Decision service variables:
- SQLResult
- XMLDocument
- XMLElement
- XMLNodeList
Decision service parameters, which are defined for each business object (variable
type) provide a mechanism for exchanging data between a rule component and a
process application. You can define Decision service parameters using the following
elements:
- A business object name
- A variable type
- A direction, which indicates whether a parameter is used as input to a Decision
service, or output from the Decision service, or both. The direction setting is
determined automatically based on how the parameter or variable is used in the
rule. For example, any parameter or variable that is referenced in a rule, but is not
modified or updated when the service is running, is identified as an IN variable.
For information about setting up Decision service parameters, see the related topic
"Adding variable types and business objects to a Decision service."
147
Procedure
To add a business object (variable type) to a Decision service, complete these
steps:
1. Open the Process Designer desktop editor.
2. Open a process application that contains the Decision service.
3. You can add a variable type from the library panel, or from the Variables tab while
you are working in the Rule service.
- To add a business object from the library panel:
A. Click the plus sign next to the Data library item.
B. In the Create New window, click Business Object.
C. In the New Business Object window, type a name for the variable type, then
click Finish.
D. Follow the procedure steps to define the new business object (variable type).
- To add a variable type while working in the Decision service:
A. Make sure you are working in the Decision service where you want to add the
new variable type.
B. Click the Variables tab.
C. Create a new variable, or select the variable where you want to add the new
variable type. For more information about adding variables, refer to the
related topic "Adding and modifying Decision service variables."
D. In the Details section, click New next to the Variable Type field.
E. In the New Business Object window, type a name for the variable type, then
click Finish.
F. Follow the procedure steps to define the new business object (variable type).
4. In the Behavior section, select a Definition Type from the list.
- Select Simple Type to create a new variable type using an existing type such as
String, Decimal, or Integer. For more information about creating simple variable
types, refer to the related topic "Creating custom variable types."
- Select Complex Structure Type to create a new complex variable type. You
can create a custom variable type by adding parameters and parameter
properties to the business object. For more information about creating complex
variable types, refer to the related topic "Adding process variables to a BPD."As
148
you are adding parameters for a complex structure type, you can see the
resulting changes to the XML schema for the variable type. To see how the
variable parameters are declared in the XML schema, open the Advanced
Properties section and click View XML Schema.
5. When you have entered all the necessary parameters and settings for the
variable type, click Save in the main toolbar.
6. Return to the Decision service editing panel, then click Select next to the
Variable Type field. The variable type that you added is listed as an available
type.
What to do next
In IBM BPM, all complex variables must be initialized before you can use the
variables in a BPD or service. Refer to the related topic "Initializing complex
variables and lists" for more information.
Parent topic:Adding and modifying Decision service variables
Related information:
Creating custom business objects in Process Designer
Declaring variables for a BPD or a service in Process Designer
149
Variable types
You can define a Decision service variable by first specifying the name of the
variable, then setting the variable type. The variable value can be a simple data type
such as a string, integer, or date. You can also define a complex variable type using
a business object that contains parameters.
Declaring the variables for a service enables the service to display and manipulate
the values that it receives from (input) and then pushes back up (output) to the main
business process.Important: You must initialize complex variable structures before
running the Decision service. In IBM BPM, all complex variables and all lists
(arrays) must be initialized before you use them in a business process definition or
service. If you do not initialize a complex variable or list, you may receive runtime
errors or notice that the controls to which the variables are bound do not behave as
expected. For more information, refer to the related topic "Initializing complex
variables and lists."
For more information about creating complex, hierarchical variable types, see the
related topic "Adding process variables to a BPD."
There are several complex variable types that are not supported when authoring
rules in a Decision service. The unsupported variable types are:
- SQLResult
150
- XMLDocument
- XMLElement
- XMLNodeList
151
3. Click the indicator next to the System Data toolkit to see its contents.
4. Click the Data category
5. Double-click the Record business object to open it. The Documentation field
provides information about the business object. The documentation informs you
that a Record is a group of ANY typed variables and that you do not need to
declare the number of ANY typed variables that you want to go into the Record.
So, the Record object is similar to a Structure object, except you do not need to
declare the type or the number of variables it contains.
For additional information about using variable types in rules, refer to the related
topic "Types of variable definition" in the WebSphere ILOG JRules InfoCenter.
152
Procedure
To test a Decision service, complete these steps:
1. Open the Process Designer desktop editor.
2. Open a process application that contains a business process definition (BPD) with
a Decision service you want to test.
3. Open the BPD and click to select the activity or decision gateway in the business
process that has the Decision service associated with it.
4. Set a breakpoint in the activity. Set breakpoints at specific locations in the
process where you want the process flow to pause during testing so that you can
determine the status of the process, and identify any errors that might have
occurred.
5. Click the Decision service name to open the rules in the rule editor.
6. Click the Run service icon
in the banner above the rule editor.
7. When Process Designer prompts you to change to the Inspector interface, click
Yes. The Inspector displays red tokens both in the BPD diagram and the
execution step tree, which provides a hierarchical view of the execution state,
showing the step that is currently running in the active process instance.
- Debugging a Decision service
Debug a rule component in a Decision service using the Inspector perspective and
the debugging feature in Process Designer. Use these testing functions to can
examine how the Decision service operates in each step of the process execution,
which provides a more detailed inspection than simply stepping through the
process.
- Exception messages in Decision service testing
You can review exception messages that result from Decision service testing. The
153
154
Procedure
1. Open the Process Designer desktop editor.
2. Open a process application in the Designer view.
3. Make sure that you are working in the Decision service that you want to test and
debug.
4. Click the Debug icon.
5. The IBM BPM Debug Service opens in a new browser window, as shown in the
following diagram:
6. Click Step in the Debug window to run the Decision service one step at a time,
or click Run to run the complete Decision service.
155
9. When you run a Decision service and an exception occurs, the Inspector clearly
identifies the error in the Execution State panel. The Inspector also tells you
where the error happened, and links directly to the source of the problem. For
more information about using the Inspector to debug errors, see the related topic
"Resolving errors."
10. The Debug service browser window captures error and exception messages.
The first few lines of the exception are displayed at the top of the browser
window. To see the complete message, click Details. To help you locate the rule
that produced the error, some exception messages refer to specific rules by their
order number, such as Rule 1, Rule 2, Rule 3, prefixed by the name of the
Decision service step, as shown in the following example:An error occurred in
QuoteLookupRule2 service, at step BalRule1.
Detail message: Object stockQ not found at run time during execution.
You must make sure that the object has been initialized.
156
at ilog.rules.res.session.IlrRuleService.executeRuleset(IlrRuleService.java:124)
at com.ibm.rules.sdk.samples.documentrules.ResultsTab$4.widgetSelected(ResultsTab.java:206)
at org.eclipse.swt.widgets.TypedListener.handleEvent(TypedListener.java:234)
at org.eclipse.swt.widgets.EventTable.sendEvent(EventTable.java:84)
at org.eclipse.swt.widgets.Display.sendEvent(Display.java:3776)
at org.eclipse.swt.widgets.Widget.sendEvent(Widget.java:1367)
at org.eclipse.swt.widgets.Widget.sendEvent(Widget.java:1390)
at org.eclipse.swt.widgets.Widget.sendEvent(Widget.java:1375)
at org.eclipse.swt.widgets.Widget.notifyListeners(Widget.java:1187)
at org.eclipse.swt.widgets.Display.runDeferredEvents(Display.java:3622)
at org.eclipse.swt.widgets.Display.readAndDispatch(Display.java:3277)
at org.eclipse.ui.internal.Workbench.runEventLoop(Workbench.java:2629)
at org.eclipse.ui.internal.Workbench.runUI(Workbench.java:2593)
at org.eclipse.ui.internal.Workbench.access$4(Workbench.java:2427)
at org.eclipse.ui.internal.Workbench$7.run(Workbench.java:670)
at org.eclipse.core.databinding.observable.Realm.runWithDefault(Realm.java:332)
at org.eclipse.ui.internal.Workbench.createAndRunWorkbench(Workbench.java:663)
at org.eclipse.ui.PlatformUI.createAndRunWorkbench(PlatformUI.java:149)
at com.ibm.rules.sdk.samples.documentrules.Application.start(Application.java:38)
at org.eclipse.equinox.internal.app.EclipseAppHandle.run(EclipseAppHandle.java:196)
157
at org.eclipse.core.runtime.internal.adaptor.EclipseAppLauncher.runApplication(EclipseAppLauncher.java:110)
at org.eclipse.core.runtime.internal.adaptor.EclipseAppLauncher.start(EclipseAppLauncher.java:79)
at org.eclipse.core.runtime.adaptor.EclipseStarter.run(EclipseStarter.java:369)
at org.eclipse.core.runtime.adaptor.EclipseStarter.run(EclipseStarter.java:179)
at sun.reflect.NativeMethodAccessorImpl.invoke0(Native Method)
at sun.reflect.NativeMethodAccessorImpl.invoke(NativeMethodAccessorImpl.java:39)
at sun.reflect.DelegatingMethodAccessorImpl.invoke(DelegatingMethodAccessorImpl.java:25)
at java.lang.reflect.Method.invoke(Method.java:597)
at org.eclipse.equinox.launcher.Main.invokeFramework(Main.java:619)
at org.eclipse.equinox.launcher.Main.basicRun(Main.java:574)
at org.eclipse.equinox.launcher.Main.run(Main.java:1407)
at org.eclipse.equinox.launcher.Main.main(Main.java:1383)
Caused by: ilog.rules.res.session.IlrSessionException: An error occurred while the rule session was invoked.:
ilog.rules.res.session.IlrSessionException: An error occurred while the rule session was invoked.
ilog.rules.res.util.IlrRemoteException: Ruleset execution error
ilog.rules.res.util.IlrRemoteException: null
at call to 'mainRuleflow flow task body'
at call to 'execute'
ilog.rules.res.util.IlrRemoteException
158
Detail message: Object CustomerName not found at run time during execution. Make sure the object has been initialized.
at com.lombardisoftware.core.TeamWorksException.asTeamWorksException(TeamWorksException.java:129)
at com.lombardisoftware.core.RegexExceptionRewriter.rewrite(RegexExceptionRewriter.java:76)
at com.lombardisoftware.core.ExceptionHandler.returnProcessedException(ExceptionHandler.java:310)
at com.lombardisoftware.servlet.ControllerServlet.doError(ControllerServlet.java:152)
at com.lombardisoftware.servlet.ControllerServlet.doCommon(ControllerServlet.java:417)
at com.lombardisoftware.servlet.ControllerServlet.doPost(ControllerServlet.java:134)
at javax.servlet.http.HttpServlet.service(HttpServlet.java:738)
at javax.servlet.http.HttpServlet.service(HttpServlet.java:831)
159
Procedure
To export rules for use in Rule Studio and the Rule Execution server, complete
these steps:
1. Export the BAL rules from your Decision service.
A. Make sure that you are editing the NotificationRulesService Decision service
and the AlertRules BAL Rule component.
B. In the AlertRules component panel, click the Decisions tab to open the rule
editor.
C. In the menu bar above the rule editor window, click the Export
icon.
D. In the Save As window, navigate to the location where you want to save the
exported rule file.
E. Enter a name for the export file, then click Save to specify the location.
You can find more information about exporting rules in the related topic about
exporting rules for use in Rule Studio.
2. Import the rules into Rule Studio.
A. Using IBM WebSphere ILOG Rule Studio, import the project .zip file to create a
new Rule Studio project.
B. Click File > Import > General > Existing Projects into Workspace.
C. Click Select archive file. Click Browse to navigate to the location where you
saved the exported rule project file and select the file.
D. Select an existing project where the rules will be imported, or create a new
Rule Studio project, then click Finish.
You can find more information about importing rules in the related topic about
configuring a remote decision service.
160
What to do next
After completing the scenario, test and debug the Decision service and the JRule
Decision service component to make sure the rules from the Rule Execution Server
are producing the results you expect. For more information about testing and
debugging a Decision service, see the related topic about testing a Decision service.
Parent topic:Building a Decision service
Related information:
Exporting rules for use in Rule Studio
Configuring a remote Decision service
Deploying from Rule Studio
Testing a Decision service
162
Procedure
To export a rule component that contains a single rule or multiple rules, complete
these steps:
1. Open the Process Designer desktop editor.
2. Open a process application in the Designer view.
3. Make sure that you are working in the Decision service that contains the rule
component you want to export.
4. In the Decision service diagram, click to select the component icon, such as a
BAL Rule, that represents the component you want to export.
5. Click the Decisions tab.
6. In the menu bar at the top of the rule editor window, click the Export
icon.
7. In the Save As window, navigate to the location where you want to save the
exported rule file.
8. Enter a name for the export file, then click Save.
Results
The export function produces an Eclipse project file with a .zip extension.
What to do next
You can import the rule project file into ILOG Rule Studio. To keep the Decision
service connected to the rules as you work on them in Rule Studio, you can replace
the BAL Rule in the Decision service with a JRule Decision Service. Refer to the
related topic "Configuring a remote Decision service" for information about
performing this procedure. For more information about importing a rule project into
ILOG Rule Studio, refer the related topic "Importing a rule project in Rule Studio" in
163
164
Procedure
1. Make sure that you are working in the Decision service where you want to add
the JRules Decision Service.
2. Remove the BAL Rule component that contains the rules you exported.
3. Drag a JRules Decision Service component from the palette to the service
diagram, and place it in the same location as the deleted BAL Rule component.
Reconnect any sequence lines to other activities or services.
4. Select the new JRules Decision Service component, then click Implementation
in the Properties tab.
5. In the Discovery section, enter the following information to connect to the Rule
Execution Server that contains the rules that you want to use.Table 1. Input
required to connect to the Rule Execution Server
Field
Server
SOAP Port
Action
Select the server that you want from
the list of ILOG Rules Server variables.
See the related topic "Setting
environment variables" for more
information.
Specify a port for the SOAP connection
if the Rule Execution Server is running
on WebSphere Application Server.
165
User name
Password
The SOAP port, user name, and password fields accept embedded JavaScript
expressions, so variables can be used to provide those values.
6. Click Connect.
7. In the Rule section, select the Rule App that you want from the menu, then
select the version that you want to use. If a secure connection to the Rule
Execution Server has not been established, the menu is not populated. In this
case, manually enter the name and version of the Rule App and Rule Set that
you want to use. The names must be accurate for the next step to work.
8. Click Generate Types.
9. In the Generating Types window, make sure that the Generate
request/response wrapper types option is not selected. Click Next.
10. Click Finish when type generation is complete.
11. In the Properties section, click Data Mapping.
12. Click the auto-map icon in upper right corner of the Input Mapping section. The
Create variables for auto-mapping window opens, listing the private variables
needed for input parameters from the selected Rule App.
13. Click to select each variable that you want to create in your Decision service and
then click OK.
14. Click the auto-map icon in upper right corner of the Output Mapping section. The
Create variables for auto-mapping window opens, listing the private variables
needed for output parameters from the selected Rule App.
15. Click to select each variable that you want to create in your Decision service and
then click OK.
16. Save the updated Decision service.
Parent topic:Exporting rules for use in Rule Studio
Related information:
Deploying from Rule Studio
166
167
procedure.
- If you connect to a Rule Execution Server that is running on an application server
other than WebSphere, you cannot list the rule applications and rule sets available
on that Rule Execution Server. In this case, you can manually enter the names of
the rule applications and rule sets that you want to use. If the names that you
provide are accurate, you can successfully generate types as described in the
following procedure.
Procedure
To build a Decision service that includes an JRules Decision Service component,
complete these steps:
1. Open the Process Designer desktop editor.
2. Open a process application in the Designer view.
3. Create a Decision service.
4. Drag a JRules Decision Service component from the palette to the service
diagram.
5. With the JRules Decision Service component selected, click the
Implementation option in the Properties tab.
6. In the Discovery section, enter the following information to connect to a Rule
Execution Server that contains deployed rule applications (Rule Apps) that you
want to use.Table 1. Input required to connect to the Rule Execution Server
Field
Server
SOAP Port
User name
Password
Action
Select the server that you want from
the list.
Specify a port for the SOAP connection
if the Rule Execution Server is running
on WebSphere Application Server.
Enter the user name to use, if
necessary, for a secure connection.
Enter the password to use, if
necessary, for a secure connection.
The SOAP port, user name, and password fields accept embedded JavaScript
expressions, so variables can be used to provide those values.
7. Click Connect.
8. In the Rule section, select the Rule App that you want from the menu, then
select the version that you want to use. If a secure connection to the Rule
Execution Server has not been established, the menu is not populated. In this
case, manually enter the name and version of the Rule App and Rule Set that
you want to use. The names must be accurate for the next step to work.
9. Click Generate Types.
10. In the Generating Types window, make sure the Generate request/response
wrapper types option is not selected. Click Next.
11. Click Finish when type generation is complete.
12. In the Properties section, click Data Mapping.
168
13. Click the auto-map icon in upper right corner of the Input Mapping section. The
Create variables for auto-mapping window opens, listing the private variables
needed for input parameters from the selected Rule App.
14. Click to select each variable that you want to create in your Decision service and
then click OK.
15. Click the auto-map icon in upper right corner of the Output Mapping section. The
Create variables for auto-mapping window opens, listing the private variables
needed for output parameters from the selected Rule App.
16. Click to select each variable that you want to create in your Decision service and
then click OK.
17. Use sequence lines to connect the JRules Decision Service component to the
Start and End Events.
18. Save the new Decision service.
What to do next
You can nest this Decision service in any other service within your process
application that requires the same logic. Be sure to adjust the input and output
variables as required for each implementation. Refer to the related topic "Declaring
and passing variables" for more information.
169
Procedure
1.
2.
3.
4.
170
14. In the rules editor, click the plus sign to add a variable (column) to the first rule
(row).
15. From the list of available variables, select amount from the request structure.
16. Type >250 as the variable value.
17. In the rules editor, click the plus sign again. Make sure the first rule (row) is
selected because you want to add another variable (column) to this rule.
18. From the list of available variables, select type from the request structure.
19. Type "director" as the variable value.
20. In the Action Requirement field for the first rule (row), type Requires
Approval .
21. In the rules editor, click the Action section to expand it.
22. For the Requires Approval requirement, enter the following JavaScript for the
Action: tw.local.approvalRequired = true;
23. In the rules editor, click the second row to select it. Create a new rule stating that
employee expenses of more than $60 require approval.
24. In the rules editor, click the third row to select it. Create a catch-all rule by typing
- for both the amount and type. The - value in a variable field indicates that any
variable value is considered a match.
25. In the Action Requirement field for the third rule (row), type Auto Approval .
26. In the Action section, enter the following JavaScript for the Auto Approval
action:tw.local.approvalRequired = false;
27. Click the Diagram tab.
28. Use the Sequence Flow tool to connect the Decision Table component and the
Start and End events.
- Authoring rules using JavaScript in a Decision Table component
You can create rules using JavaScript in a Decision Table component.
- Decision Table controls
You can use the toolbar options in the conditions editor window to add, remove, or
move conditions in the table.
- Specifying variable values using JavaScript
You can use JavaScript in rules to set variable values.
Parent topic:Building a Decision service
Related information:
Adding a Decision service to a process
Declaring variables for a BPD or a service in Process Designer
171
Procedure
1.
2.
3.
4.
172
15. In the rules editor, click the second row to select it. Create a new rule so that
expenses of more than $60 for employees requires approval.
16. In the rules editor, click the third row to select it. Create your catch-all condition
by typing - for both the amount and type. The - value in a variable field indicates
that any variable value is considered a match.
17. In the Action Requirement field for the third rule (row), type Auto Approval.
18. In the Action section, enter the following JavaScript for the Auto Approval
action: tw.local.approvalRequired = false; The rules editor includes the
rules shown in the following image:
For more information about specifying variable values using JavaScript, refer to
the related topic "Specifying variable values using JavaScript."
19. Click the Diagram tab.
20. Use the Sequence Flow tool to connect the Decision Table component and the
Start and End events.
21. Name the Decision Table component and save your work.
What to do next
You can now nest this Decision service in any other service within your process
application that requires this logic. Be sure to adjust the input and output variables
as required for each implementation.
For more information about the controls in the decisions editor window, such as the
up and down arrows, refer to the related topic "Decision Table controls."
173
Description
Add a new variable (column) or remove
the selected variable (column) from the
rule.
Move the selected rule (row) up or down
in the table or remove the selected rule
(row) from the table.
174
Description
Matches the exact string ok (no quotation
marks)
Matches the exact number 1.4
Matches either of the strings A or B
Matches anything except the strings A or
B
Matches any number between 1 and 5
(inclusive)
Matches any number greater than 3
Matches any number less than 3
Matches any number greater than or
equal to 3
Matches any number less than or equal
to 3
Matches 1, 3, or 5
Matches 1, 3, or any number between 5
and 10 (inclusive)
Matches any number except 1, 3, or a
number between 5 and 10 (inclusive)
Matches the Boolean value true
Matches the Boolean value false
175
BAL reference
A reference guide to the Business Action Language (BAL), which is used to author
rules in IBM Business Process Manager, is available in the IBM WebSphere ILOG
JRules InfoCenter.
The BAL language reference topics list the predefined BAL constructs that you can
use to build business rules, and the operators that you can use in rule statements to
perform arithmetic operations, associate or negate conditions, and compare
expressions. For more information, refer to the related topics in the IBM WebSphere
ILOG JRules InfoCenter, in the section "Business Action Language (BAL)." A related
link is provided.
Parent topic:Building a Decision service
Related reference:
BAL Reference, IBM WebSphere ILOG JRules InfoCenter
176
177
Procedure
1. Open the Process Designer desktop editor.
2. Open a process application in the Designer view.
3. In New Service, enter a name for the service and click Finish.IBM Process
Designer displays the diagram of the service with the default Start Event and
End Event components.
4. Create the client-side human service artifact. You can do this from the
navigation tree or you can do this from the activity wizard. For information, see
Building a client-side human service and Implementing a BPD task using a
client-side human service. Process Designer opens the new client-side human
service in a web browser.
178
5. In the Variables page, define the data used by artifacts within the client-side
human service. This data consists of data passed into the client-side human
service, data used only within the service, and data passed out of the client-side
human service. For information, see Declaring variables for a human service.
6. In the Diagram page, add coaches, client-side scripts, called services, and
exclusive gateways to the client-side human service diagram. Connect them to
define the flow for the client-side human service.
7. For each element in the client-side human service diagram, define its properties.
For information, see the following topics:
- Building coaches
- Implementing exclusive gateways in client-side human services
- Calling another service from a client-side human service
8. If the client-side human service is within a BPD or a case type activity, map the
input and output data. For information, see Mapping input and output data for an
activity or step.
9. If the client-side human service is within a BPD or a case instance and you want
users to be able to resume work at a particular point with minimal loss, select a
flow line in the diagram and then select to save the execution context. For
information, see Saving the state of a client-side human service during execution
.
10. To validate the data in a coach, add a coach validation pattern to the client-side
human service diagram. For information, see Validating client-side coaches
using client-side validation.
11. To postpone work in a coach, add a postpone pattern to the client-side human
service diagram. For information, see Enabling work to be postponed and
resumed at run time.
12. Set how users interact with the client-side human service by setting its exposure.
By default, the client-side human service is not exposed, which means that it is
contained within a BPD or case type. However, you can also make it available in
Process Portal or through a URL. For information, see Exposing client-side
human services.
13. Optimize how users see the coaches by adding HTML meta tags to the clientside human service. For information, see Adding HTML meta tags to client-side
human services for mobile device optimization.
14. Set what happens after the client-side human service completes. By default, the
user sees the default page of the application that launched the client-side human
service. For example, if the user started the client-side human service in
Process Portal, the user sees the Process Portal home page when the clientside human service is complete. For information, see Navigation options for after
service completion.
15. Run the client-side human service and debug any errors that might occur. For
information, see Running and debugging client-side human services.
Parent topic:Building services
179
Procedure
1. Open the Process Designer desktop editor.
2. Open a process application in the Designer view.
3. In New Service, enter a name for the service and click Finish.IBM Process
Designer displays the diagram of the service with the default Start Event and
End Event components.
4. In a BPD diagram, drop an activity into a non-system lane and then rename the
activity. Activities dropped into any lane but System have the default heritage
human service implementation. In the remaining steps, you replace this default
heritage human service with your own.
5. Right-click the activity and select Activity Wizard from the list of options.
6. In the Setup Activity page of the wizard, select Create a new Service or
Process. .
7. If the BPD has variables that are defined, click Next. In the Parameters page of
the wizard, set whether each business process variable is an input or output of
the heritage human service. For example, if you have business process variable
that is named request and the heritage human service is to collect data to
create that request for the server, set its Input to false and Output to true.
The heritage human service then provides the data for the subsequent process
activities to act upon.
180
8. Click Finish. The activity now has an associated heritage human service that
following steps:
A. Create a snapshot of the toolkit.
B. Activate the toolkit snapshot. For more information, see Activating snapshots
for use with IBM Process Portal.
C. Add the toolkit snapshot as a dependency to a process application. For more
information, see Creating, changing, and deleting a toolkit dependency in the
Designer view.
182
Procedure
1. Open the Process Designer desktop editor.
2. Open a process application in the Designer view.
3. In New Service, enter a name for the service and click Finish.IBM Process
Designer displays the diagram of the service with the default Start Event and End
Event components.
4. Add variables that the service will use as input or output. You can also add private
variables. See Declaring variables for a BPD or a service in Process Designer for
information.
5. Add components to the service diagram and then set up the sequence flow.For
more information about components, see Service components in Process
Designer.
6. Configure the components in the sequence flow. For example, if you are using a
Server Script component, add a script in the Implementation properties.
7. Save changes. The Ajax service is available for use in Coach Views.
Example
To view an example of an Ajax service, the following Ajax services are provided in
the Coaches (8.0) toolkit: Coaches Localized Messages Loader, Default
Autocompletion Service, and Default Selection Service.
Parent topic:Building services
Related information:
Calling Ajax services from coach views
Building an Ajax service with heritage coaches
183
Procedure
1. Open the Process Designer desktop editor.
2. Open a process application in the Designer view.
3. In New Service, enter a name for the service and click Finish.IBM Process
Designer displays the diagram of the service with the default Start Event and End
Event components.
4. Select the Variables tab, and add the variables that your integration service will
use as input or output and also add private variables that the service will use. See
Declaring variables for a BPD or a service in Process Designer for information.
5. Select the Diagram tab, and add the appropriate components to the service and
then connect the components to create the flow. For information about the
components that you can add to the diagram, see Service components in Process
Designer. In particular, add one or more of the following components:
- Web Service Integration component. For information about integrating web
services, see Creating outbound integrations to web services.
- Java Integration component.
- Nested service component by dragging an integration service or other service
onto the diagram. This action attaches the service to the component.
- Content Integration component. For information about this component and how
to configure it, see Building a service that integrates with an ECM system or the
IBM BPM document store.
Tip: You can also use the Invoke UCA component for integration. See
Undercover agents.
6. Configure the components in the flow. For the integration components listed in the
previous step, configure them so that they interact with the external system. In
184
particular, for the Web Service Integration, Java Integration, Content Integration,
and nested service components, map the data used in the task flow to the input
and output for the component:
A. Click the Data Mapping option in the properties. Because you already created
the input and output variables for the nested service, the Data Mapping tab
includes these variables.
B. From the Input Mapping section, you can map each variable using one of the
following ways:
- Use
to suggest mappings. If the automatic mapper does not find a
variable, you can create a private variable for the mapping.
- Use and then select the appropriate variable.
C. In the Output Mapping section, do similar mappings for the output variables.
7. If you want the results of the service to be cached for unique combinations of
input parameter values, enable and configure the service result cache.
A. Select the Overview tab, then in the Service Result Cache section, select
Enable caching of service results. The cache configuration fields are
displayed.Restriction: The service result cache setting works only for top-level
services that are called directly. If a service is called within another service, the
cache setting does not apply.
B. By default, when caching is enabled, the results for each combination of input
parameter values are kept in the cache for 12 hours. To change the caching
period, in the Cache results for section, use the Days, Hours, Minutes, and
Seconds fields to select the duration that you want.Important: You might be
able to improve the performance of some services by using the cache,
however you must take care when you decide how long to cache results for,
and might need to tune the size of the cache to avoid memory problems. By
default, the cache stores up to 4096 results. You can change the size of the
cache by setting a different value for <service-result-cache-size> in the
100Custom.xml file, inside the <server merge="mergeChildren"> section.
Example
See the integration services included in the System Data (TWSYS) toolkit for
implementation examples.
Parent topic:Building services
Related information:
Integrating with web services, Java and databases
Examples of building services with heritage coaches
Integrating BPDs with IBM Case Manager cases
Integrating with Enterprise Content Management (ECM) systems
185
Procedure
1. Open the Process Designer desktop editor.
2. Open a process application in the Designer view.
3. In New Service, enter a name for the service and click Finish.IBM Process
Designer displays the diagram of the service with the default Start Event and End
Event components.
4. Optional: In the Documentation field, add a description for your service.
5. In the Parameters section, add input, output, and error parameters.An input
parameter defines the name and type of data your business process sends to the
service in Integration Designer.
An output parameter defines the name and type of data your business process
receives from the service in Integration Designer.
An error parameter identifies an error or fault that might be thrown by the service
186
7. An Open in Integration Designer button lets you see the implementation created
in Integration Designer. It can only be used if Integration Designer is available.
8. Save your work. From the menu, select File > Save All
Results
An advanced integration service can be used as implementation of a user task or a
system task. If used by a user task, it is assigned as specified via the assignments
of the user task. If used by a system task, it is run by the system user.
An advanced integration service can also be emulated. In emulation, it behaves in
the following way:
- If used by a user task, it is assigned as specified via the Assignments of the user
task.
- If used by a system task then it will use the All users group.
When All users is shown in emulation, any user selected will require authentication.
Select the user you are currently authenticated as and enter your credentials.
187
What to do next
Use the information in Authoring services in IBM Integration Designer to continue
developing your advanced integration service. You can add services, service-related
functions, BPEL processes. monitor models, and more.
Parent topic:Building services
188
189
Modeling events
Events in IBM Business Process Manager can be triggered by a due date passing,
an exception, or a incoming message from an external system. You can add events
to your BPDs that can occur at the beginning, during, or at the end of a process.
Use events to track data, manage errors, and retrieve information about the
execution of your BPDs.
- Event types
Learn about the types of events available in IBM BPM and when to use each type.
- Modeling delays, escalations, and timeouts by using timer events
To specify when an activity occurs or when another path in the process should be
taken, use intermediate and boundary events of the timer type.
- Modeling message events
Use a message event to represent a point in your process where an incoming
message is received or where an outgoing message is sent.
- Enabling users to perform ad hoc actions (deprecated)
Use an ad hoc event when you need to include ad hoc actions that can be run at
any time during process execution.
- Modeling event gateways
Use an event gateway to model a point in the process execution where only one
of several paths can be followed, depending on events that occur.
- Handling errors using error events
When you design a business process definition (BPD) or a service, provide logic
to recover from possible errors that might be generated in the runtime application.
- Using Service Component Architecture to interact with processes
There are several ways to start and interact with business process definition
(BPD) instances using Service Component Architecture (SCA). You can use
receiving message events to create or interact with BPD instances.
- Undercover agents
An undercover agent (UCA) is attached to a message event or a content event in
a business process definition (BPD) and calls a service to handle the event.
Parent topic:Modeling processes
190
Event types
Learn about the types of events available in IBM BPM and when to use each type.
You can include the following types of events in your IBM BPM Business Process
Definitions (BPDs):
- Start event
- Use to model the start of a process, a linked process, a subprocess or an event
subprocess. A Start event is automatically included each time you create a
business process definition (BPD). A BPD can include multiple Start events
(one Start event with an implementation of None and multiple Start events with
an implementation of Message) if you need to be able to start the process more
than one way. Start events have the following implementation options:
Table 1. Implementation options for Start events
Option
None
Description
Use the None implementation option if
you want to enable process
participants to start a process manually
from IBM Process Portal. (For an
example of such a process, see
Creating a business process definition
(BPD).) Or, you can use this
implementation option when you intend
to use a process as a linked process
from another higher level process.
Use the Message implementation
option if you want an incoming
message to kick off a process (see
Using start message events ) or an
event subprocess (see Modeling event
subprocesses).
Use the Ad Hoc implementation option
when you need to include ad hoc
actions that can be run at any time
during process execution. For
example, you can include an ad hoc
event to enable users to cancel a
customer order at any time during the
ordering process. See Deprecated:
Enabling users to perform ad hoc
actions for more information.
Use the Content implementation option
if you want an ECM event to kick off a
process.
Message
Ad Hoc
Content
191
- Intermediate events can be attached to activities within your BPDs or they can
be included in the process flow, connected with sequence flows. Attached
intermediate events are known as boundary events.Intermediate events have
the following implementation options:Table 2. Implementation options for
Intermediate events
Option
Message
Description
Use the Message implementation
option to model a message event that
is received or sent. The Message
implementation option is available for
events included in the process flow
and events attached to an activity.
When attached to an activity, the event
receives only messages. See Using
intermediate and boundary message
events to receive messages and Using
intermediate message events and
message end events to send
messages for more information.
Use the Timer implementation option
to model escalation paths or delays in
your BPDs. Using a timer event, you
can specify a time interval after or
before an activity is performed. The
Timer implementation option is
available for events included in the
process flow and events attached to an
activity. See Modeling timer events for
more information.
Use the Tracking implementation
option to indicate a point in a process
at which you want IBM BPM to capture
the runtime data for reporting
purposes. The Tracking
implementation option is available only
for events included in the process flow.
Use the Error implementation option to
catch errors and to handle errors with
login in the process flow. The Error
implementation option is available only
for events attached to an activity. For
an example of how to use intermediate
error events, see Handling errors using
error events.
Use the Content implementation option
to model an ECM event that is
received. The Content implementation
option is available for events included
in the process flow and events
attached to an activity.
Timer
Tracking
Error
Content
192
- End event
- Use to model the end of a process. An End event is automatically included
each time you create a BPD.End events have the following implementation
options:Table 3. Implementation options for End events
Option
None
Description
Use the None implementation option
when you want to indicate the end of
activities on a particular path.
Use the Error implementation option
when you want to throw an error to
parent processes or to error event
subprocesses. See Handling errors
using error events for more
information.
Use the Terminate implementation
option when you want to close running
tasks associated with a process and
cancel outstanding timers. You can set
these options for the terminate event:
Terminate Entire Process
InstanceTerminates the entire process
instance. If you do not select this
option, only the process that contains
the event and its subprocesses is
terminated. If an entire process
instance is terminated, the process
shows a status of Terminated in the
Inspector. Delete All Terminated
Instance Runtime DataCleans up the
runtime state for the executing
instance. All database states for the
runtime instance and any generated
tracking data is deleted. This setting
only applies to top-level process
instance cleanup, and is ignored
otherwise.
Use the Message implementation
option when you want to send a
message. For example, you might
want to send a message at the
conclusion of each process instance
that is received by a start message
event in another process or processes
so that the completion of one process
starts another related process or
processes. See Using message end
events for more information.
Error
Terminate
Message
193
194
The process waits for the timer in the timer event to elapse before it proceeds to the
next node. For example, if your BPD has an activity that emails offers to customers
and an activity that has the sales team contact these customers two days later,
model a delay by using a timer intermediate event between the two activities. The
delay ensures that two days pass between the emails and when the sales team
starts contacting the customers.
For modeling escalations, use timer boundary intermediate events. Timer boundary
from the timer boundary event to a subsequent activity. For an example, see Hiring
tutorial: Add a timer intermediate event in the Hiring Tutorial or see the Hiring
Sample.
For modeling timeouts, use timer intermediate events that are included in event
gateways. If the other intermediate events in the event gateway group do not trigger
before the timer elapses, the timer intermediate event triggers instead. When you
add an event gateway, Process Designer automatically adds a timer intermediate
event and a message event to the event gateway group. You configure the timer
Procedure
To model a delay, escalation, or timeout:
1. Open the Process Designer desktop editor.
2. Open a BPD in the Designer view.
3. Drag an intermediate event
from the palette.
- To create a delay, drop the intermediate event into a blank area of the canvas.
- To create an escalation, drop the intermediate event onto an activity. This action
attaches the intermediate event as a boundary event. To verify that you have
created a boundary event, select the activity and check that the outline of the
activity includes the event icon.To have multiple escalations, attach more than
one intermediate events to the activity. Each boundary event triggers a different
escalation path.
- To create a timeout, drop the intermediate event into an event gateway group.
4. Select the intermediate event and open its Implementation properties.
5. From the list of Intermediate Event types, select Timer.
6. If you are creating an escalation and you want the activity to remain open after
the timer is triggered, in the Boundary Event Details section clear the Interrupt
Activity check box. For example, imagine that you create a timer boundary event
for a user task. The human service that is associated with the user task has
coaches. If you want the users to complete the coaches even after the timer
elapses, clear the Interrupt Activity check box. If you clear the Interrupt
Activity check box, you can choose to have the escalation occur only once by
clearing the Repeatable check box.
7. Specify when to start the timer for the timer event by setting the Timer properties:
A. Set what starts the timer with the Trigger On field. For example, to start the
timer when the due date for an activity elapses, select After Due Date. The
due date is calculated according to the work schedule for the BPD and the
priority settings for the activity. For more information, see Setting the work
schedule for a BPD. Note: To trigger the timer event before or after a custom
196
date, you can enter the JavaScript to determine the custom date in the
Custom Date field. Your JavaScript must return a Date object, which specifies
when to start the timer.
B. Optional: To modify the trigger, use the Before or after difference field. For
example, if you want start the timer a day after the due date of the activity, type
1 into the field and select Days from the associated list.
C. Optional: To further modify the trigger, use the Tolerance Interval field. For
example, specify a tolerance level of one hour if you want the escalation to
occur one day and one hour after the due date of the activity.
8. If you are creating an escalation or timeout, create the flow that the process uses
after the timer elapses. The escalation path is the logic that the process performs
if the timer elapses before the activity it is attached to finishes. Similarly, the
timeout path is the logic that the process performs if the timer elapses before
another event in the event gateway group triggers.
9. Connect the timer event:
- For a delay, use the Sequence Flow tool to connect the timer event to the rest of
the process.
- For an escalation or timeout, connect the timer event to the escalation or timeout
path.
Parent topic:Modeling events
Related information:
Hiring tutorial
197
Implementation
Message that is configured
to receive (Start events
can only receive
messages)
198
When to use
Use to model the start of a
process if you want an
incoming message event
to kick off the process. A
BPD can include more
than one start message
event.Use as the start
event for an event
subprocess when you want
the event subprocess to be
triggered upon receipt of a
message.
Intermediate event
Intermediate event
End event
When you create a message event, you can cut and paste or copy and paste that
message event within the same BPD or from one BPD into another BPD. A
message can cause a process instance to be created, and can be received by a
running process that contains one or more appropriate message events.
Before you include any type of message event that uses an undercover agent as the
triggering mechanism, you should be aware of the following:
- You can configure message events to consume messages. If you do, when a
message is delivered to a running process, the message is consumed by the first
message event in the BPD that can accept it (as determined by the undercover
agent that is attached to the message event). When a message is consumed, it will
not be processed again by that message event, or any other message event in the
BPD instance that can accept it, should the execution of the BPD instance loop
back and reach the same message event(s). If a new instance of the message is
delivered to the process instance, this message is available for consumption again
and is accepted by the message event.
- Message events can be used to enable roll-forward scenarios in which the same
message needs to be passed through multiple steps until it reaches the
appropriate step in the process where it is to be consumed. To enable rolling a
message forward through multiple message events, enable the Consume Message
option only for the last message event in the chain of roll-forward message events.
You can also use conditions to further control message consumption.
- Occasionally, you might need to set conditions on the processing of incoming
messages. If the condition that you specify evaluates to true, the message is
accepted and processing continues-otherwise, it is stopped. Because the message
199
condition is evaluated before the message values can be passed to the input
variables of the process definition, the message values are passed to the condition
in a special namespace, tw.message. If the message condition evaluates to true,
the values are passed from the tw.message namespace to the BPD input
variables.
- Using start message events
If you want a process or event subprocess to start when a message is received,
use a Start Message Event in your business process definition (BPD) or inside
your event subprocess.
- Using intermediate and boundary message events to receive messages
You can include an intermediate message event in your business process
definition (BPD) when you want to model a message event that is received during
execution of a process. When the process execution reaches an intermediate
message event, if a matching message is stored in the system, it is passed to the
message event, otherwise, further execution along that path is blocked until an
incoming message arrives that matches.
- Using intermediate message events and message end events to send
messages
You can include an intermediate message event in your business process
definition (BPD) when you want to model a message event that is sent during
execution of a process, or a message end event when you want to send a
message at an end of a path.
- Setting the target for a UCA message event
While you are configuring an undercover agent (UCA) message event in a
business process definition (BPD) or configuring an Invoke UCA step in a service
to use a message event, you can exercise some control over which snapshots use
the event. You can override the default target by selecting a check box in the
implementation settings for the UCA that carries the event.
- Using message end events
You can use a message end event when you want to send a message at an end
of a path.
Parent topic:Modeling events
Related information:
Modeling event subprocesses
200
Procedure
1. Open the Process Designer desktop editor.
2. Open a BPD or drill into an event subprocess, then drag a Start Event component
from the palette onto the diagram.
3. On the Properties tab, click Implementation.
4. In the Start Event Details section, select the start event type Message.
5. If the start event is part of an event subprocess, the Start Event Details section
shows the following options.
A. If receiving and processing the message causes completion of the parent
process, make sure that the Interrupt Parent Process option is selected,
which is the default setting. When this option is selected, when the subprocess
reaches its end, the parent instance is completed. Otherwise, clear the
selection so that the parent process is not interrupted or completed when the
message is received.
201
- If you selected an existing service definition, the associated events are added
to the list of events that the definition includes.
- To restore the default value, click the X (delete) icon.
- If you specify the same SCA identifier for multiple message events, any
changes to the service identifier or message object type affect all the events
that provide the service. Making such changes can break data mappings for
the events.
Tip: If your BPD includes more than one start message, each one should use
a different SCA service identifier. Otherwise, if multiple start message events
specify the same SCA service identifier, the start event that receives the start
message is selected arbitrarily.If you specify the same SCA identifier for
multiple message events, the service interface can trigger multiple events in
the BPD. However, each incoming message is received by only one of the
events. Which event receives the message, or whether it is stored for future
delivery, depends on whether a correlating process instance is found, and if
so, which compatible message events are in the waiting state. For details of
the semantics, see Using Service Component Architecture to interact with
processes.
Important: It is possible to define unintentionally the same service identifier
on multiple events. For example, if different events have identical names
(which is shown as an error on the General tab), or if different service
identifiers map onto identical NMToken strings. If such a naming clash
happens, you can break the unintended polymorphism by renaming the
duplicate event names and then click X (delete) to restore the default service
identifier name.
8. Specify the correlation and output mapping.
A. On the Properties tab, click Data Mapping.
B. Open the Correlation and Output Mapping section.
C. Select the output variable that you want to use to for correlation. The value that
is assigned to it ensures that the parameter values of the runtime message are
passed to the correct BPD instance. The variable that is selected for
correlation is identified by an assignment symbol ( ). This correlation ensures
that the parameter values of the runtime message are passed to the correct
BPD instance.
- For undercover agents that are implemented using a complex variable rather
than a service, you can select the complex variable or the top-level child
properties of the variable for mapping or correlation.
If you use SCA, you must select a variable that is marked as a
process instance identifier that ensures that the message is passed to the
correct BPD instance based on the value of that variable.
D. Map each output variable to a local variable in the BPD. For each variable,
click the variable selector icon to map each output variable to be passed into a
local variable in the BPD.
For example, if the start message event starts an instance of an on-boarding
process when an employee record is created in your HR system, you can map
the employee information from the undercover agent to a local variable in the
BPD.
203
If your start message event is inside an event subprocess, you must select a
variable to be used for correlating process instances. Correlation allows IBM BPM
to identify the process instance that the message is meant for.
For example, an employee number might be used to uniquely identify an instance
of an on-boarding process. Selecting this variable for correlation ensures that
when the data related to a specific employee number is passed to the event
subprocess, the appropriate instance of the on-boarding process is found.
Parent topic:Modeling message events
Related information:
Using Service Component Architecture to interact with processes
204
Procedure
1. Open the Process Designer desktop editor.
2. Open a BPD and drag an Intermediate Message Event component from the
palette onto the BPD diagram. It can be dragged to the swimlane or attached to
an activity. When the event is attached to an activity, the event is known as a
boundary event and it is included in the outline of the activity.
3. On the Properties tab, click Implementation.
4. Select the event type Message.
A. If you dragged the Intermediate Message Event component onto the BPD
diagram, in the Intermediate Event Details section, select the intermediate
event type Message.
B. If you dragged the Intermediate Message Event component onto an activity, in
the Boundary Event Details section, select the intermediate event type
205
Message.
5. If the intermediate message event is a boundary event, use the Boundary Event
Details section to specify its behavior:
A. If receiving the message signals completion of the activity, make sure that the
Interrupt Activity option is selected, which is the default setting. Otherwise,
clear the selection, so that the activity is not interrupted and completed when
the message is received.
B. If Interrupt Activity is not selected, the Repeatable option is available. If the
boundary message event can be triggered more than once, select the
Repeatable option so that the attached activity can receive multiple messages.
6. To use a UCA for triggering an intermediate message event, complete the
following actions in the Message Trigger section.
A. For Triggering Mechanism, select UCA.
B. To select an existing undercover agent, click Select next to the Attached
Message UCA field.
C. To create an undercover agent, click New. See Undercover agents.
D. In the Condition text box, type a JavaScript expression if you want to define
conditions under which the message event is processed.If you do specify a
condition and the condition evaluates to true, the message is accepted and
processing continues. If the condition evaluates to false, processing stops. In
most cases, special message conditions are not necessary because you
should implement each message event with a separate undercover agent.
E. If you want the incoming message to be consumed after it is received by the
message event, enable Consume Message. Refer to the bulleted list in
Modeling message events to learn more about message consumption.
F. To allow the message event to receive an incoming message that arrives
before a process is at a point where the event can accept the message, select
Durable Subscription. The durable subscription causes the message to be
stored until the message event is reached. Only the most recently received
message is stored. Tip: If you occasionally use inbound messages and
undercover agents, consider using durable subscription events.
When Durable Subscription is selected, incoming messages are persisted in
the database. The durable messages accumulate, even if you select the check
box to make them consumable. Periodically use the
BPMDeleteDurableMessages command for deleting durable subscription
events.
Important: The sender and receiver of the message must both use the same
undercover agent. For example, if the sender of the message is a message end
event in another BPD, then select the same undercover agent for both the
receiving intermediate event and the sending message end event in the other
BPD.
Tip: Undercover agents must have a schedule type of On Event to function as a
message trigger. Plus, the service that is attached to the selected undercover
agent must have one or more input variables so that it can pass and correlate
information from the event.
7.
To use an SCA service for triggering an intermediate message event,
complete the following actions in the Message Trigger section.
A. For Triggering Mechanism, select SCA Service.
206
B. For Message Object Type, click Select to select a business object (BO) type,
click New to define a new BO type, or leave it to be set automatically when you
select a service definition. The business object type that you select
determines the output parameters of the intermediate message event. The
message object type must be a complex type.
C. For Service Identifier, a default value is provided, based on the name of the
event, as shown in the BPD diagram. If you want, you can either specify a
different service identifier name, or select one from the drop-down list of
services that match the selected message object type. If you enter a name, it is
restricted to using the NMToken character set.
- If you selected an existing service definition and the message object type was
not set, the message object type is updated to match the service definition.
- The service identifier is used with the BPD name to generate a unique SCA
service for this event point. The generated service interface name is
displayed.
- If you selected an existing service definition, the associated events are added
to the list of events that the definition includes.
- If you specify the same SCA identifier for multiple message events, any
changes to the service identifier or message object type affect all the events
that provide the service. Making such changes can break data mappings for
the events.
- To restore the default value, click the X (delete) icon.
Tip:If you specify the same SCA identifier for multiple message events, the
service interface can trigger multiple events in the BPD. However, each
incoming message is received by only one of the events. Which event receives
the message, or whether it is stored for future delivery, depends on whether a
correlating process instance is found, and if so, which compatible message
events are in the waiting state. For details of the semantics, see Using Service
Component Architecture to interact with processes.
Important: It is possible to define unintentionally the same service identifier on
multiple events. For example, if different events have identical names (which is
shown as an error on the General tab), or if different service identifiers map
onto identical NMToken strings. If such a naming clash happens, you can
break the unintended polymorphism by renaming the duplicate event names
and then click X (delete) to restore the default service identifier name.
8. Specify the correlation and output mapping.
A. On the Properties tab, click Data Mapping.
B. Open the Correlation and Output Mapping section.
C. Select the output variable that you want to use to for correlation. The value that
is assigned to it ensures that the parameter values of the runtime message are
passed to the correct BPD instance. The variable that is selected for
correlation is identified by an assignment symbol ( ). This correlation ensures
that the parameter values of the runtime message are passed to the correct
BPD instance.
- For undercover agents that are implemented using a complex variable rather
than a service, you can select the complex variable or the top-level child
properties of the variable for mapping or correlation.
207
208
Procedure
1. Open the Process Designer desktop editor.
2. Open a BPD and drag an intermediate or end event from the palette onto the
BPD diagram.
3. In the text box that displays over the event, type a name for the event.
4. Use the Sequence Flow tool to connect the event as needed.
5. In the diagram, select the new event.
6. On the Properties tab, click Implementation. The default implementation for
intermediate events that are included in the process flow is Message. If you are
creating a message end event, select Message end event as the implementation
type.
7. If you are creating an intermediate message event, select Sending from the
available message types in the drop-down list. By default, all message end events
are sending message end events.
8. In the Message Trigger section, complete one of the following actions.
- To select an existing undercover agent, click Select next to the Attached
Message UCA field.
- To create an undercover agent, click New. See Undercover agents.
Important: The sender and receiver of the message must both use the same
undercover agent. For example, if the sender of the message is a message end
event in another BPD, then select the same undercover agent for both the
receiving intermediate event and the sending message end event in the other
BPD.
Tip: Undercover agents must have a schedule type of On Event to function as a
message trigger. Plus, the service that is attached to the selected undercover
agent must have one or more input variables so that it can pass and correlate
209
210
211
Procedure
1. Open the Process Designer desktop editor.
2. Open a BPD and drag an end event from the palette onto the diagram.
3. In the text box that appears over the event, type a name for the event.
4. Click the Implementation option in the properties.
5. Click the drop-down list and select Message from the end event types. By default,
message end events can only send messages.
6. In the Message Trigger section, click Select next to Attached UCA to select an
existing undercover agent.To create an undercover agent, click New. See
Undercover agents.
Undercover agents must have a schedule type of On Event to function as a
message trigger. Plus, the service attached to the selected undercover agent
must have one or more input variables so that it can pass and correlate
information from the event.
Note: Ensure that the sender and receiver of the message both use the same
undercover agent. For example, if the receiver of the message is an message
intermediate event in another BPD, then select the same undercover agent for
both the sending message end event and the receiving intermediate event in the
other BPD.
7. Click the Data Mapping option in the properties.
8. In the Input section, click the variable selector icon on the right side of each field
to map each undercover agent output variable to a local variable in the BPD. Click
the Use default check box if you want to use a default value from the attached
undercover agent for a particular variable. When you enable this check box, the
variable selector icon is disabled.
Parent topic:Modeling message events
212
213
Procedure
1.
2.
3.
4.
214
14. In the Activity Wizard - Setup Activity window, make the following selections:
Table 1. Recommended selections in the Activity Wizard - Setup Activity window
Option
Activity Type
Service Selection
Selection
User Task
Select the Create a New Service or
Process option.
In the Name field, type Show Data for the new service. (For this example, name
the new Human service the same as the corresponding activity in the BPD.)
15. In the Activity Wizard - Setup Activity window, click Next.
16. In the Activity Wizard - Parameters window, choose the process variables from
the regular process to use as input and output for the new service for the ad hoc
process.For the private variable named requisition, leave the Input field set
to true and change the Output field to false. These settings reflect the fact that
our sample ad hoc event simply displays the requisition data and does not pass
back modified data. For other variables, click to change the setting from true to
false under the Input and Output field. Click Finish.
The new service is created and attached to the activity. The new service
includes a single Coach.
17. Double-click the Show Data activity in the Ad hoc event lane in the BPD.The
new service opens and you can see the service diagram.
18. Click the Coaches tab and then click the listed Coach to see its controls.
Because we used the Activity Wizard, the Coach includes a form element for
each of the parameters in the requisition variable.
19. Save your work and then follow the instructions in Deprecated: Testing a sample
ad hoc action.
Parent topic:Enabling users to perform ad hoc actions (deprecated)
Related information:
Hiring tutorial
Configuring access to Process Portal action policies
215
Procedure
1.
2.
3.
4.
What to do next
The ad hoc event and user task that you added to the BPD diagram enables you to
view the requisition information at any time during running of the regular process.
216
Related information:
Getting started with Process Portal
Configuring access to Process Portal action policies
217
Procedure
1. Open the Process Designer desktop editor.
2. Open a business process definition (BPD).
3. Drag a gateway from the palette to the process diagram.
4. In the text box that displays over the gateway, type a name for the gateway.
5. Click the General option in the properties.
6. In the Behavior section of the general properties, click the drop-down list and
select Event Gateway from the available gateway types. To streamline
configuration of an event gateway, IBM Process Designer automatically adds an
intermediate message event (receiving) and an intermediate timer event to the
process diagram. These intermediate events are grouped with the event gateway
in the process diagram.
7. Add any additional events required by the gateway configuration by dragging
them from the palette to the event gateway group in the process diagram. Only
intermediate message events and intermediate timer events are allowed. The
minimum number of events is two, and you can add as many as you require.
8. Click an event in the group and then select the Implementation option in the
properties.
A. To configure an intermediate message event, follow the steps in Using
intermediate and boundary message events to receive messages.
B. To configure an intermediate timer event, follow the steps in Modeling timer
events.
218
219
220
Errors caught
Only errors with the same code and data
type
Errors with the same code, unless they
are already caught by an event, as
specified by the preceding rule
Errors with the same data type, unless
they are already caught by an event, as
specified by the preceding rules
All errors that are not already caught by
an event, as specified by the preceding
rules
Note: Multiple events that are defined in the same context and with the same
constraints cause nondeterministic runtime behavior.
Specifying the variable name in the mapping controls the filtering by error data type.
If the type of the variable and the type of the error data that is displayed on the
Properties tab do not match, the variable type determines the behavior.
- Handling errors in BPDs
When modeling error handling as part of your business process definitions
(BPDs), you can catch errors using error intermediate events or event
subprocesses, and you can throw errors using error end events.
- Handling errors in services
For services, you can use error intermediate events to catch errors, and you can
use error end events to throw errors.
- Error events in models from V7.5.x and earlier
If you have Process Designer models from V7.5.x or earlier that use error events,
the earlier error handling behavior is still available.
Parent topic:Modeling events
221
222
Description
Catches specified errors or all
error intermediate event
at the
errorsProvides error handling logic for
boundary of an activity (error boundary
errors raised by the activity that it is
event)
attached to
error event subprocess that starts with an Catches specified or all errorsProvides
error handling logic for errors raised by
error start event
activities of the BPD, subprocess, or
event subprocess that directly contains
the error event subprocess
Throws an error
error end event
- To reuse the error-handling flow for multiple tasks in your process, use event
subprocesses. To reuse an error-handling flow using attached events, you must
attach an intermediate event for each of the tasks and then connect those events
to the error-handling flow.
- Define data objects that you can access only from within the event subprocess.
You can define only those data objects that belong to a subprocess. The parent
process is not cluttered with unnecessary variables.
For more information about event subprocesses, see Modeling event subprocesses
.
Throwing errors
You can use an error end event in your BPD to specify an error code and map to an
error type on errors thrown from the flow of a BPD or a service.
When working with either error events or event subprocesses, think about whether
errors can be handled immediately, and normal processing can continue, or if
another error can be thrown at another level. Then implement error handling from
the bottom up. In other cases, it might be more efficient and readable if subprocess
can be reused. Build each linked process and service so that errors can be captured
and corrected. If a correction is not possible at the lowest level of the
implementation, you can allow the error to move up a level by not including an error
event or include an error event to rethrow the error to the calling service or process,
as shown in the following section.
For example, to ensure that any errors that might occur during process run time are
captured, you can create a high-level BPD that includes an activity to call the main
process as a linked process and then one additional activity with an underlying
service to implement error handling as shown in the following image:
This type of design ensures that errors thrown from underlying processes and
services are propagated up and handled appropriately.
224
Description
Catches errors from the step
To determine whether to use error events in your services, consider the following
points:
- You must attach error intermediate events to steps in your service. The attached
error event is known as a error boundary event.
- Include error intermediate events in the service flow so that they can act as global
error handlers in the service.
- Determine whether errors can be handled immediately, and normal processing can
be continue, or if another error can be thrown at another level. Then implement
error handling from the bottom up.
- Use an error end event to throw a specific error. You can specify an error code and
error data for the error.
- Consider specifying the error data to catch specific errors. For example, you could
filter on the error code for the types of errors that are caught and map the error
code to a variable after the errors are caught. When all errors are caught, or if only
an error code is specified, the error data is captured in an XMLElement in the
tw.system.error variable.
might reenter the service and run the normal flow with corrected data.
To handle errors in a service and wire back to the normal flow in the same service,
use one or more error boundary events with specific errors and the catchAll options.
Note: An error intermediate event in the service flow also catches errors thrown
through error end events of that service flow.
Important: The error intermediate event can cause endless loops if follow-up
activities after the event throw a runtime or a modeled error. The service engine
prevents these loops. In some cases, it might be useful to model a loop with an
intermediate error end event. To allow looping, add the following entry to the
100Custom.xml file: <server> <!-- insert if not already present -->
<execution-context> <!-- insert if not already present -->
<prevent-intermediate-error-loop
merge="replace">false</prevent-intermediate-error-loop>
Changing this property will globally suppress the error loop detection of the service
engine. Change this property only if all your models are free of endless error loops.
226
227
228
Instance-based correlation
If a request message must be received by an existing instance of a BPD, you must
specify a correlation variable to identify the intended instance that receives the
message.
SCA message correlation requires that at least one of the BPD's variables is marked
as being a process instance identifier. The correlation variable can be written to only
once. The value that is assigned to the correlation variable must uniquely identify
the instance. Normally, business data is assigned to a process instance identifier
variable. For example, the correlation variable might be assigned an employee
number from the start message. All messages that are intended for the same
instance must include the same value for the correlation variable to identify the
appropriate process instance. The value that is used to identify a process instance
cannot be reused to identify a new instance until after the first instance is in the
completed or terminated state, or the instance is deleted.Important: You must
ensure that the process instance identifier variable is initialized before any message
is sent for the instance. Because the correlation matching is only performed when
the message arrives, if a message arrives before the process instance identifier
variable is initialized, it can never match with a process instance, and can never
trigger a receiving message event.
If a message is posted before the a suitable message receive event is in a waiting
state, the message is stored. The message will be received by the first matching
message receive event that goes into the waiting state.
You can specify that the BPD exposes only one service, which is implemented by
different receiving message events of the BPD. To do so, specify the same service
identifier and message object type for different message events in the BPD. When a
message is received, one of the receiving message events will process it. Which
event receives the message depends on whether a correlating process instance is
found, and if so, which event is active, or reached first.
- If a process instance matches the instance identifier value in the message, then
the following rules are applied:
- If the instance has exactly one matching event (intermediate, boundary, or a start
event for an event subprocess) that is in the waiting state, the matching event
receives the message.
- If the instance has multiple matching events that are in the waiting state, one of
them is selected arbitrarily to receive the message.
- If the instance does not have any matching event in the waiting state, the
message is stored until an event that can receive the message becomes active.
- If no process instance matches the instance identifier value in the message and
there is a start process message event that matches the message type, a new
instance of the BPD is created, and the start message event receives the
message.
Warning: It is possible to define unintentionally the same service interface for
multiple events. For example, if different events have identical names (which is
shown as an error on the General tab), or if different service identifiers map onto
identical NMToken strings, then different events share the same service interface. If
this naming conflict happens, you can break the naming conflict by renaming the
duplicate event names and then restoring the default service identifier name.
Task overview
To use SCA to interact with a BPD, you must complete the following actions:
1. Using Process Designer:You can either use the implicitly provided services of the
BPD, or use the services that are provided for a receiving message event in
which SCA is specified as the triggering mechanism. For the former you do not
have to do anything, for the latter you must specify the corresponding receiving
message events.
A. If SCA messages interact with existing BPD instances, use instance-based
correlation for the message event subprocess, intermediate receiving message
events, or boundary message events. For that, you must mark one or more of
the process variables as process instance identifiers. See Declaring variables
for a BPD or a service in Process Designer.
B. Ensure that the process variable that identifies a BPD instance is assigned a
suitable value. The value must be assigned before any SCA message can
230
231
Undercover agents
An undercover agent (UCA) is attached to a message event or a content event in a
business process definition (BPD) and calls a service to handle the event.
An undercover agent is started by an event. For example, when a message event is
received from an external system, an undercover agent is needed to start the
appropriate service in response to the message.
Message events can originate from any of the following components:
- BPDs (see Modeling message events)
- web services that you create (see Publishing IBM Business Process Manager web
services)
- messages that you post to the JMS listener (see Posting a message to IBM
Business Process Manager Event Manager)
When an undercover agent runs, it starts an IBM Business Process Manager
service or a BPD in response to the event.
When you include a message event or a content event in a BPD, you must attach an
undercover agent to the event. For example, when a message event is received
from an external system, an undercover agent is needed to trigger the message
event in the BPD in response to the message.
If you want to run the startBpdWithName application programming interface (API) to
start a BPD instance inside an undercover agent, set the <enable-start-bpdfrom-uca> property to true in the 100Custom.xml file or another override file.
Restart the product, and check the TeamworksConfiguration.running.xml file to
ensure that the setting has the appropriate value. The property is set to false by
default, and if you don't change it, you might have errors that prevent the BPD from
starting.
- Creating and configuring an undercover agent for a message event
You can create an undercover agent (UCA) that invokes a particular service as
the result of an incoming or an outgoing message event.
- Creating and configuring an undercover agent for a scheduled message
event
You can create an undercover agent (UCA) that invokes a service as the result of
a message event that occurs on a regular schedule.
- Creating and configuring an undercover agent for a content event
To obtain information about document or folder events on an Enterprise Content
Management (ECM) server, you must create and configure a content undercover
agent that works with your event subscription. A content undercover agent (UCA)
is used to initiate a BPM Start or Intermediate event when specific content changes
occur on an ECM server. It is conceptually similar to a message undercover agent,
but it has a specialized Content marker to differentiate it from a Message marker.
Parent topic:Modeling events
Related information:
Creating inbound integrations
Creating an undercover agent
232
233
Procedure
1. Open the Process Designer desktop editor.
2. In the Designer view, click the plus (+) sign next to Implementation and then
select Undercover Agent from the list.
3. In the New Undercover Agent window, enter the following information:
- Name: Type a name for the new undercover agent.
- Schedule Type: Select On Event from the drop-down list.
- Click Finish.
4. In the Common section, you can type a description of the undercover agent in
the Documentation text box.
5. In the Scheduler section, you can see the type of schedule for the current
undercover agent in the Schedule Type field.
6. Beside the Event Marker area, accept the default event marker Message. If you
want, you can later click Select and then select Content. (The Content
selection is used to work with content events that originate from ECM servers.
By comparison, the Message selection is used to work with message events
that originate from business process definitions, JMS listeners, or web services
that you have created.)
7. Under Details, click the drop-down list next to Queue Name to select the queue
that you want from the following options:
Table 1. Available queue
options
Option
Async Queue
SYNC_QUEUE_1
SYNC_QUEUE_2
Description
Allows Event Manager jobs to run at
the same time.
Forces one job to finish before the next
job can start. By default, three
synchronous queues are available.
Forces one job to finish before the next
job can start. By default, three
synchronous queues are available.
234
SYNC_QUEUE_3
Note: For more information about Event Manager jobs, monitoring those jobs,
and creating and maintaining Event Manager execution queues, see
Maintaining and monitoring IBM Business Process Manager Event Manager.
When you install and run the process on a Process Server in a test or production
environment, the queue that you select must exist in that environment in order
for the undercover agent to run.
8. Beside the Implementation area, accept the default selection Variable or select
Service (if necessary). Use a variable implementation to pass events directly
from the undercover agent to the business process definition (BPD). By
comparison, use a service implementation to process information about events
by adding business logic or decisions.
9. If you selected Variable, the default variable type NameValuePair is already
selected. However, you can click Select to choose a different existing variable
type or you can click New to create a new variable type.
10. If you selected Service, the default attached service Default BPD Event is
already selected. However, you can click Select to choose a different existing
service or you can click New to create a new general system service.
11. Ensure that the Enabled check box is selected.Note: If this check box is not
selected, the Event Manager does not run the undercover agent when the
message is received or sent. (The Event Manager monitor might show that the
Event Manager has run the undercover agent, but if this check box is not
selected, the execution does not occur.)
12. In the Parameter Mapping section, select the Use Default check box if you want
to use the default value of the input variable in the attached service. If the input
variable of the attached service does not have a default value, this check box is
disabled.Type a value in the text box if you want to map a constant value to the
input variable of the attached service. For example, you might use a constant for
testing purposes.
In most cases, the required values are included in the incoming message event
and no action is required here.
13. In the Event section, IBM BPM provides a default ID that is unique in the Event
Message field. This ID represents the event message for IBM BPM processing.
If you are posting a message to IBM BPM Event Manager from an external
system, the ID in this field is the event name that you need to include in the XML
message. See Posting a message to IBM Business Process Manager Event
Manager for more information about the message structure.
If you are using a web service to enable an external application to call into IBM
BPM, you should not alter this ID. IBM BPM seamlessly uses this ID if you
create an inbound integration as described in Building a sample inbound
integration.
14. Open the BPD that includes the message event to which you want to attach the
undercover agent. For example, if you want a particular process to start when a
new customer record is created in an external system, you can associate the
start event in the BPD with an undercover agent that handles that incoming
235
event.Note: Ensure that the sender and receiver of a message both use the
same undercover agent. For example, if the sender of a message is a message
end event in another BPD, then select the same undercover agent for both the
receiving start event and the sending message end event in the other BPD.
Tip: If you occasionally use inbound messages, consider using durable
subscription events. Durable subscriptions are Java Message Service (JMS)
subscriptions that persist and store subscribed messages even when the client
is not connected. The durable messages accumulate, even if you select the
check box to make them consumable. Periodically use the
BPMDeleteDurableMessages command for deleting durable subscription
events.
15. Click the message event in the BPD to select it.
16. Click the Implementation option in the properties.
17. In the Message Trigger section, click Select next to Attached UCA and pick the
undercover agent created in the previous steps.
18. Click Save and switch back to the undercover agent editor.
19. In the undercover agent editor, you can click Run Now if you want to test the
undercover agent and monitor it as described in Maintaining and monitoring IBM
Business Process Manager Event Manager.
Parent topic:Undercover agents
Related information:
Attaching the undercover agent to the message event
BPMDeleteDurableMessages command
236
Procedure
1. Open the Process Designer desktop editor.
2. Open a process application in the Designer view.
3. Select the plus (+) sign next to Implementation and then select Undercover
Agent from the list.
4. In the New Undercover Agent window, enter the following information:
- Name: Type a name for the new undercover agent.
- Schedule Type: Select Time Elapsed from the drop-down list.
- Click Finish.
5. In the Common section, you can type a description of the undercover agent in
the Documentation text box.
6. In the Scheduler section, you can see the type of schedule for the current
undercover agent. After you have configured and saved the undercover agent,
you can click Run Now if you want to test the undercover agent and monitor it
as described in Maintaining and monitoring IBM Business Process Manager
Event Manager.
7. Under Details, click the drop-down list next to Queue Name to select the queue
that you want from the following options:
Table 1. Available queue
options
Option
Async Queue
SYNC_QUEUE_1
SYNC_QUEUE_2
Description
Allows Event Manager jobs to run at
the same time.
Forces one job to finish before the next
job can start. By default, three
synchronous queues are available.
Forces one job to finish before the next
job can start. By default, three
synchronous queues are available.
237
SYNC_QUEUE_3
Note: For more information about Event Manager jobs, monitoring those jobs,
and creating and maintaining Event Manager execution queues, see
Maintaining and monitoring IBM Business Process Manager Event Manager.
When you install and run the process on a Process Server in a test or production
environment, the queue that you select must exist in that environment in order
for the undercover agent to run.
8. Ensure the service shown as the Attached Service is the one that you want to
invoke according to the specified schedule. If not, click Select to choose a
different service.
9. Ensure that the Enabled check box is selected.Note: If this check box is not
selected, the undercover agent will not run.
10. In the Parameter Mapping section, select the Use Default check box if you want
to use the default value of the input variable in the attached service. If the input
variable of the attached service does not have a default value, this check box is
disabled.Type a value in the text box if you want to manually map a constant
value to the input variable of the attached service. For example, you might use a
constant for testing purposes.
11. Scroll down to the Time Schedule section and use the available options to
establish a schedule.For example, if you want to start the attached service every
weekday at midnight, use the Ctrl key to select the options that are selected in
the following image:
You can select multiple contiguous items by pressing the Shift key, clicking the
first in the series, and then clicking the last in the series. To select multiple noncontiguous items, press the Ctrl key each time you click an item.
Note: The On the hour value is selected by default in the last column of the
Time Schedule section. If you clear this selection and you do not make any other
selection in the column, the On the hour value will be used even though it is not
selected.
Note: If you select the First value and also select multiple weekdays, the
undercover agent will run on the first occurrence of each selected day for the
selected months. For example, if you select First and also select Monday,
Tuesday, and Thursday, the undercover agent will run on the first Monday,
Tuesday, and Thursday that occur in the selected months. Similarly, if you select
the Last value and also select multiple weekdays, the undercover agent will run
on the last occurrence of each selected day for the selected months. For
example, if you select Last and also select Monday, Tuesday, and Thursday,
the undercover agent will run on the last Monday, Tuesday, and Thursday that
occur in the selected months.
238
12. Open the BPD that includes the message event to which you want to attach the
undercover agent. For example, if you want a particular process to start at the
same time each day, you can associate the start message event in the BPD with
an undercover agent that establishes the required schedule.
13. Click the message event in the BPD to select it.
14. Click the Implementation option in the properties.
15. In the Message Trigger section, click Select next to Attached UCA and select
the undercover agent created in the previous steps.
Parent topic:Undercover agents
239
Procedure
1. Open the Process Designer desktop editor.
2. Open a process application in the Designer view.
3. Create a content undercover agent by completing the following steps:
A. Click the plus (+) icon beside Implementation and then select Undercover
Agent. The New Undercover Agent wizard opens.
B. In the Name field, specify a name for the new undercover agent.
C. In the Schedule Type drop-down list, select On Event.
D. Click Finish. The undercover agent opens in the undercover agent editor.
4. Configure the content undercover agent by completing the following steps in the
undercover agent editor:
A. Beside the Event Marker area, click Select and then select Content. (Use the
Content selection to work with content events that originate from ECM
servers. By comparison, the Message selection is used to work with message
events that originate from BPDs, JMS listeners, or web services that you have
created.)
B. Beside the Implementation area, accept the default selection Variable or
select Service (if necessary). Use a variable implementation to pass events
directly from the undercover agent to the business process definition (BPD).
By comparison, use a service implementation to process information about
events by adding business logic or decisions.
C. If you accepted Variable as your implementation, the default variable type
ECMContentEvent is used and it cannot be changed.
D. If you selected Service as your implementation, the default attached service
Default ECM Event is already selected. However, you can click Select beside
240
the Attached Service area and choose a different attached service for the
undercover agent.
E. Ensure that the Enabled check box is selected, which enables the content
undercover agent to run.
F. In the Parameter Mapping section, select the Use Default check box if you
want to use the default value of the input variable in the attached service. If the
input variable of the attached service does not have a default value, this check
box is disabled. You can type a value in the field to manually map a constant
value to the input variable of the attached service. For example, you might use
a constant for testing purposes.
G. Click Save.
H. If you accepted the Content event marker and you need to create an event
subscription for the undercover agent, click Add Event Subscription and
follow the instructions in the topic Creating and configuring event subscriptions
.
I. After you have configured and saved the content undercover agent, you can
click Run Now to test the content undercover agent and monitor it as
described in Maintaining and monitoring IBM Business Process Manager
Event Manager.
Results
The new configured content undercover agent is displayed in the Undercover
Agents section of the Implementation library list.
241
Procedure
To enter documentation for an artifact:
1. Open the artifact in Process Designer.
2. Switch to the Overview tab.
3. Enter your text in the Documentation field.
What to do next
Restriction: The documentation field allows a maximum of 200,000 characters,
including hidden formatting characters. Long documentation that approaches this
limit can impact performance. Consider the following options:
- Reduce the size of the documentation.
- Simplify the formatting, such as removing tables and text formatting.
- Move the documentation content to a separate file and link to or attach the file. See
Linking to external information.
242
Adding a link
You can add a link to an external resource in a process application or toolkit
description.
Procedure
To add a link to an external source, complete the following steps:
1. Log in to IBM Process Center or IBM Process Designer and select a process
application or toolkit.
2. Do either of the following steps:
A. In Process Center, click the Manage tab. The
B. In Process Designer, select the artifact in the process application or toolkit for
which you want to add a link to an external resource and click the Overview
tab, or open the Properties editor.
3. Do either of the following steps:
- In Process Center, click inside the Description field.
- In Process Designer, click the Documentation Edit link in the Common Section
of the Overview, or in the Properties editor.
In Process Center, the inline editor displays showing you a standard formatting
toolbar. In Process Designer, a rich text editor window opens that shows a
standard formatting toolbar.
4. To add a link, click the Insert Link icon on the toolbar and complete the fields in
the Add Link window. When you access a specific content source, you might be
prompted to log in to the source. You must log in with a user ID and password
that provides access to that content source. The link source must be registered as
a remote content source with Process Center using the Create Registration
option. For more information about registering a remote content source, see
Using remote assets.Note: In Process Center, the attachment link type is
243
available only when you create a new snapshot, or edit an existing snapshot.
When you create a new snapshot, you can create the attachment link either to an
existing design file, or to a new file. When you edit an existing snapshot, you can
create the attachment link only to an existing design file. Also, when you create
an attachment link to a new file:
- The files that you add must be 100 MB or less.
- The name of the file that you add must be less than 64 alphanumeric characters.
- The accumulated total file size for a process application must be less than 600
megabytes.
5. Optional: You can specify the relationship type of the link and the asset type that
the link is associated to. The asset types are determined by the type of content
source that you are using in your project. When you select a link type, it can be
modified by any asset type that you select. For example, if you select
Implements as the relationship type and Defect as the asset type, the
description of the artifact is modified with an option that defines the link as
implementing a defect. The link displays as a defect. The following table identifies
the default link and asset types.Table 1. Link options
Type
Relationship Type
Unspecified
Affected by
Implements
Related to
Resolves
Tested by
Uses
Asset Type
Unspecified
Change Request
Defect
Requirement
Service
Test
Description
No specific link type is specified
Defines the link target as affected what
is defined by the selected asset type
Defines the link target as implementing
what is defined by the selected asset
type
Defines the link target as associated to
what is defined by the selected asset
type
Defines the link target as resolving what
is defined by the selected asset type
Defines the link target as tested by what
is defined by the selected asset type
Defines the link target as using what is
defined by the selected asset type
No specific asset type is specified
Defines the asset type as a change
request
Defines the asset type as a defect
Defines the asset types a project
requirement
Defines the asset type as a service that
can be implemented
Defines the asset type as a test
244
Procedure
To edit an existing link, complete the following steps:
1. Log in to Process Center or Process Designer and select a process application or
toolkit.
2. Do either of the following steps:
- In Process Center, click the Manage tab.
- In Process Designer, select the artifact in the process application or toolkit for
which you want to add a link to an external resource and click the Overview tab,
or open the Properties editor.
3. Do either of the following steps:
- In Process Center, click inside the Description field.
- In Process Designer, click Edit in the Overview tab or the Properties editor.
In Process Center, the inline editor displays showing you a standard formatting
toolbar. In Process Designer, a rich text editor window opens that shows a
standard formatting toolbar.
4. Place the cursor on the link and click the link text. The Edit Link window opens.
You can now edit the link or the link name.
245
246
247
248
Procedure
1. Open the Process Designer desktop editor.
2. Open a process application in the Designer view.
3. Click the plus sign next to Implementation and select External Implementation
from the list of components.
4. Supply a descriptive name for the new external implementation.
5. Click Finish.
6. In the Common section of External Implementation, optionally provide a
description in the Documentation text box.
7. In the Custom Properties section, specify the properties to identify and run the
external application.For example, for an external Eclipse RCP application, you
might add custom properties to pass the Java Class name of the form to use for
an activity or an application-specific identifier to look up the implementation by
another means. Alternatively, you might use the external application name or
system ID to find the implementation.
You can create parameters with a special meaning. For example, suppose you
need to pass a URL address as a custom property? In the Custom Properties
249
section you could use url as the name and then add a value that is the URL itself
(http://mysite.com...).
You can also use this section to pass data to variables in a client that were
instantiated with a constructor.
Note: You can add custom properties to pass static metadata about the
implementation to the external application. For dynamic data, which would be
different for each process instance or environment, use the Parameter Details
section as outlined in the following step.
8. In the Parameters section, add the parameters for the external implementation by
clicking Add Input or Add Output.For example, if the external implementation
provides an interface in which a manager can either approve or reject an expense
report, it might include input parameters for the expense report data and output
parameters for the decision that the manager makes and the justification for his
decision.
Be sure to account for all process data that the external implementation requires
to complete successfully and also for any data required from the external activity
by subsequent activities.
9. Click Save in the main toolbar.
What to do next
You can use an external implementation with Process Portal. In the Custom
Properties section add the URL for Process Portal as shown earlier. In the article,
Load External Activity URLs from Teamworks Portal, you will see how to retrieve a
task ID from the business process to work with a specific task.
250
Procedure
1. Open the Process Designer desktop editor.
2. Open a BPD and click the activity that you want to implement using a custom
application.
3. Click the Implementation tab in the properties.
4. Under Implementation, select the User Task or System Task option from the
displayed list.
5. Click the Select button to choose an external implementation from the library.If
the external implementation has not been created, click the New button and
follow the steps in Creating an external implementation to create a new external
implementation.
6. In the Task Header section, specify the following properties: Table 1. Properties
in the Task Header section
Property
Subject
Narrative
Action
Type a descriptive subject for the task
that is generated in IBM Process Portal
when you run the BPD. You can also
use the IBM Business Process
Manager embedded JavaScript syntax
(for example,
<#=tw.local.mySubject#>) to
express the subject.
Type an optional description. You can
also use the IBM BPM embedded
JavaScript syntax to express the
narrative. Restriction: Do not use
JavaScript variable references in task
narratives if you need the data to be
available after the task completes.
Once a task is complete, IBM BPM
removes the data for completed tasks
to conserve space. Instead, store the
data items in another location, such as
a database.
251
Note: For the following properties (in the Priority Settings section) you can click
the JS button for an option if you prefer to use a JavaScript expression with
predefined variables to establish the priority settings.
7. For the Priority field, click the drop-down list to select one of the default priority
codes: Very Urgent, Urgent, Normal, Low, or Very Low.
8. For the Due In field, you can enter a value in the text box and then choose
Minutes, Hours, or Days from the drop-down list. (When you choose Days, you
can use the text box after the drop-down list to include hours and minutes in
your specification.) You also have the option of using the variable selector next
to the text box to choose an existing variable from the library. at run time, the
variable should reflect the value that you want for the time period. Be sure to
select the option that you want from the drop-down list: Minutes, Hours, or Days.
9. For the Time Period field, click the drop-down list to select one of the options.
For example, select 24x7 if you want 24 hours a day, seven days a week to be
the time period in which the resulting tasks from the current activity can be due.
Note: You can leave the Schedule, Timezone, and Holiday Schedule fields set
to (use default). If you do, the work schedule specified for the BPD is used. See
Setting the work schedule for a BPD for more information.
10. For the Time Zone field, click the drop-down list to select the time zone that you
want to apply to the tasks that result from the current activity. For example, you
can select US/Pacific for users who work in California.
11. For the Holiday Schedule field, you can leave the setting at (use default) as
described in the preceding note or you can click the JS button if you prefer to
use a JavaScript expression. Each Holiday Schedule is made up of a list of
Dates. If you choose JavaScript, you can enter either a String (or Stringgenerated JavaScript) or JavaScript that returns a TWHolidaySchedule variable.
If you use a String, then IBM BPM looks up the holiday schedule by name
according to those rules. If you use a TWHolidaySchedule variable, then IBM
BPM assumes that the holiday schedule is filled in appropriately. (Go to the
System Data toolkit and open the TWHolidaySchedule variable to view its
parameters.)
12. Click the Data Mapping tab in the properties.Because you added the input and
output parameters for the external implementation when you created it, the Data
Mapping tab for the activity in the BPD should include those parameters.
Under Input Mapping, click the auto-map icon in the upper-right corner, and then
click the auto-map icon in the upper-right corner of the Output Mapping section.
For more information about mapping variables, see Business objects and
variables in Process Designer.
13. Save the implementation.
Parent topic:Using external implementations
Previous topic:Creating an external implementation
252
Inbound
Description
253
Java Integration
Content Integration
Invoke UCA
Description
Uses a SOAP connection to access
objects from a web service. A Web
Service Integration step hides the
complexity of the underlying WSDL,
SOAP request, and SOAP response. It
also converts inputs into the appropriate
XML and outputs into the appropriate
IBM BPM variables.Attention: The
RPC/encoded WSDL support is
deprecated in IBM BPM V8. Consider
replacing RPC/encoded web services
with documentation/literal wrapped web
services. For more information, see
Deprecated and removed features of IBM
Business Process Manager V8.5.5
Calls methods from a Java class and
interfaces with most third-party Java
APIs, and thus supports various
integration scenarios.
Enables business processes that are
developed in Process Designer to work
with an Enterprise Content Management
system.
Uses an undercover agent (UCA) to
invoke an IBM BPM service or a
business process definition (BPD).
management data.Table 2. Step types that can be used in an IBM Case Manager
Integration Service implementation
Integration step type
IBM Case Manager Integration
Invoke UCA
Description
Enables business processes that are
developed in Process Designer to work
with an IBM Case Manager case
management solution.
Invokes an IBM BPM service or a BPD..
255
256
257
SOAP headers
Use a SOAP header to include application-specific context information in the web
service SOAP request and response messages.
SOAP is a lightweight, XML-based protocol that you can use to exchange
information in a decentralized, distributed environment. You can use SOAP to query
and return information and to invoke services across the Internet with SOAP
messages.
SOAP messages are exchanged in a request-and-response format. When IBM
Business Process Manager sends a request to a web service, the web service
returns the requested values. These values are specified in a SOAP message.
This XML-based protocol consists of three parts:
- An envelope, which defines what is in the message and how to process it
- A set of encoding rules for expressing instances of application-defined data types
- A convention for representing procedure calls and responses
Each SOAP message must contain a SOAP envelope element. The SOAP envelope
describes what is in the message and provides instructions about how to process it.
The SOAP envelope has two child elements: a body (required) and a header
(optional). All the elements must be declared in the namespace for the SOAP
envelope.
The SOAP body element contains the SOAP message that is associated with a web
services request or response. The body typically contains the value of input
parameters for a request message and the value of output parameters for a
response message.
The SOAP header is an optional section in the SOAP envelope, although some
WSDL files require that a SOAP header is passed with each request. A SOAP
header contains application-specific context information (for example, security or
encryption information) that is associated with the SOAP request or response
message. There is only one SOAP header section in a SOAP request. If the SOAP
header element is present, it must be the first child element of the envelope
element. SOAP headers can be input, output, or input and output, and you do not
need to specify them in the WSDL file.
Important: For outbound web services, if you have defined the SOAP header in the
header section of a web service integration component, use the same type that is
defined in the WSDL file, or use the basic XML schema definition (XSD) type.
Otherwise, you cannot automatically map the SOAP header variable or change its
values from the data mappings section.
In IBM BPM Standard, you can populate a SOAP header in the following ways:
- Define the SOAP header in the WSDL definition as part of the SOAP binding. You
indicate these headers by by using a <soap:header> tag in the <wsdl:input> and
<wsdl:output> elements in the WSDL file. When IBM BPM sends a request to the
server that hosts the web service, the SOAP message includes the SOAP header.
- Copy headers directly from system variables, or from user-defined variables of the
correct type, into the predefined request and response SOAP header data types.
This SOAP header is considered implicit because it is not part of the SOAP
258
binding. For more information, see Creating implicit SOAP headers for outbound
web service integrations.
- Capture an incoming SOAP header in the response. In the Properties view, select
the Data Mapping tab and map the incoming SOAP header to an existing
SOAPHeaders variable. System variables are supplied or you can create your own
variables of the SOAPHeaders type. This SOAP header is also considered implicit
because it is not defined in the WSDL file.
259
260
Procedure
1. Create an integration service that includes a web service integration component.
2. Select the web service integration component and click the Variables tab above
the diagram area.
3. Create the private variable that you will later map to the SOAP header of the
request message. To add a single header entry to the request message, use the
variable type SOAPHeader. To add multiple headers to the request message, use
the variable type SOAPHeaders.
4. Initialize the variable that you created in step 3. You can initialize the variable in
three ways:
- Define a default value on the page where you created the variable.
- Add JavaScript code to a server script component.
- Click Pre & Post and add JavaScript code to the Pre-execution Assignments
section
The following example of JavaScript code initializes a private variable,
requestHeader, which is of the type SOAPHeader and contains a single header
entry: tw.local.requestHeader.name = "sessionId";
tw.local.requestHeader.nameSpace = "http://acme.com";
tw.local.requestHeader.value = "<x:sessionId xmlns:x=\"http://acme.com\">1237314</x:sessionId>";
Note: Make sure namespaces are fully qualified, as they are in the examples.
Note: Try to avoid white spaces in a SOAP header value. Best practice is to add
the XML snippet without any extra white space.
You can include more than one header. The following example of JavaScript
code initializes two SOAP headers and adds them to the requestHeaders private
variable, which is of the type SOAPHeaders and contains multiple headers: //
Initialize the "subscriptionId" header
var header1 = new tw.object.SOAPHeader();
header1.name = "subscriptionId";
header1.nameSpace = "http://acme.com";
header1.value = "<x:subscriptionId xmlns:x=\"http://acme.com\">123-4567-9012</x:subscriptionId>";
261
5. On the Data Mapping tab of the Properties view, in the Input Header Mapping
section, add your newly created variable (either requestHeader or
requestHeaders) to map it to a request SOAP header.
6. Complete the definition of the web service integration.
7. Run the integration service by clicking Run Service and verify that the SOAP
headers are added to the request message.
Parent topic:Creating implicit SOAP headers for outbound web service integrations
Related information:
Retrieving SOAP headers from the SOAP response message
262
Procedure
1. Select the web service integration component and click the Variables tab above
the diagram area.
2. Create the private variable of the type SOAPHeaders. This variable will receive the
header entries from the SOAP response message.
3. On the Data Mapping tab of the Properties view, in the Output Header Mapping
section, map your newly created variable to the response SOAP header. When
the web service invocation finishes, this variable is initialized for you and it
contains all the SOAP header entries from the SOAP response message.
4. To access the headers that have been received by the variable, add JavaScript
code to Post-execution Assignments on the Pre & Post tab or add a server
script component after the web service integration component and add the code
there. The following example shows how to access the header entries. In this
example, the private variable tw.local.responseHeaders is defined on the
Variables tab and mapped to the response SOAP header on the Data Mapping
tab.var myHeader = new tw.object.SOAPHeader();
var numHeaders = tw.local.responseHeaders.headers.listLength();
for (var i = 0; i < numHeaders; i++) {
if (tw.local.responseHeaders.headers[i].name == "header1") {
myHeader = tw.local.responseHeaders.headers[i];
}
}
263
Procedure
1. Open the Process Designer desktop editor.
2. Open a process application.
3. Select the Servers tab from the Process App Settings editor. You see the
Process App Settings editor when you first click Open in Designer from a
newly created process application in the Process Center. Alternatively you can
select Process App Settings from the drop-down list on the toolbar in Process
Designer.
4. Beneath the Servers heading click Add. Beneath the Server Details heading,
enter a meaningful name for the server. From the drop-down list in the Type field,
select Web Service. Add a meaningful description of the server in the
Description field.
264
You can enter text in these fields or text that is wrapped by <# ... #> control
characters; that is, as JavaScript code.
- Security and Policy: Determines the type of security you use.
- Use Basic Security: This selection means either no security or security
through a combination of user name and password, digital signatures, and
encryption certificates.
- Authentication: Specifies the type of authentication. Authentication ensures
that the parties in a transaction are who they claim to be.
- None: No authentication is required.
- HTTP Authentication: User name and password are passed in a header
element of a message.
- UsernameToken (password in plaintext): The username token passes the
user name and password. The password is in text.
- UsernameToken (password in digest): The username token passes the
user name and password. The password is in digest form, which means it is
a hash value. A hash value for a user name and password makes these
values more difficult to detect.
- Username: The user name that is registered at the server.
- Password: The password that is registered at the server.
- Client certificate alias: The alias for the client certificate; that is the alias
name that identifies where the client certificate is located.
- Sign request: Select if you require messages from the client to be signed.
- Expect encrypted response: Select if the client expects an encrypted
response message.
- Server certificate alias: The alias for the server certificate; that is the alias
name that identifies where the server certificate is located.
- Encrypt request: Select if you require the request message to be encrypted.
- Expect signed response: Select if you want to verify a signed response
message from the server.
- Use Policy Set: This selection means that a policy set is used to define the
configuration and security requirements for the web service.
- Policy Set: Specifies the name of the application policy set. Click Select to
choose the policy set. The list that you will see depends on the policies
available on the server. Some default application policy sets include:
WSHTTPS default, WSAddressing default, and Username WSSecurity
default. You can also create more application policy sets in the WebSphere
Application Server Administrative Console. Deselecting a policy set also
removes the policy binding.
- Policy Binding: Specifies the name of the general client policy set binding,
which contains system-specific configuration parameters like username and
password information. Click Select to choose the policy binding. The list you
see depends on the policy set bindings available on the server. Default policy
set bindings include: Client sample and Client sample V2. You can also
create more policy set bindings in the WebSphere Application Server
Administrative Console. Deselecting removes the policy binding.
6. Save your work. From the menu, select File > Save All.
266
267
Procedure
1. In the Process Designer Designer view, create an integration service for the
process application.
2. Drag a Web Service Integration component from the palette to the diagram, and
click the component to open the properties.
3. Specify the location and properties of the web service WSDL file by clicking the
Implementation properties tab. Select the Discovery Scheme you want from the
drop-down list.From process application settings lets you select a configuration
from the web service server configurations. Provide inline configuration lets
you specify your own web service configuration as shown in the following sub
steps.
A. Enter a value in the WSDL URI field. You can enter a URL, or use the
Registry Explorer to discover it.
1. Click Browse to start the Registry Explorer, and then select the registry type
from the list.
2. Select a registry URL or enter a new one.
3. For protected web services, enable the Is Protected check box, and provide
the user name and password, and click Next.
4. Enter the name of the web service and click Search services. You can
include wildcard characters in the name; for a UDDI registry use a percent
268
sign (%), for a WebSphere Service Registry and Repository registry use an
asterisk (*).
5. Select a web service, click Next to see detailed information, and then Finish
.
If you use the Registry Explorer, the WSDL URL, Protected WSDL,
Username, and Password fields are populated automatically. If you enter the
URL manually, you must also provide the other information about the WSDL
file if needed.
B. Click Discover to find the WSDL file and obtain the list of operations. Then
select an operation from the list.
C. Optional: Specify that the endpoint address URL can be overridden and
provide an alternative endpoint address. You might want to specify an
alternative endpoint address, for example, if you have different endpoints for
development, test, staging, and production environments; or if your production
environment does not have direct internet access and requests are routed
through a proxy server or gateway.
You can enter the new address as a String value, for example,
https://provider.com/services/myService, or as a JavaScript expression
that is wrapped by <#...#>.
D. Extract the input and output variables from the WSDL file that are needed by
the web service by clicking Generate Types. You can map the input and
output variables in two ways. In the Properties view, select the Data Mapping
tab and click the "Auto-map web service connector input (or output)
parameters" icon. You can also manually create the variables using the
functions in the Variables tab. Then you can map these variables to the web
service input and output parameters in the Data Mapping section.If your web
service integration component calls an inbound web service created in IBM
BPM, you must generate the types again in the following cases.
- The inbound web service uses a business object defined in the System Data
Toolkit. The namespace of that business object uses a host name and a port
specification. The types must be generated again for business objects
(complex types) if the inbound web service's host name or port is changed in
this situation.
- The Target namespace scheme field is changed to the Per snapshot name
value. The namespace of the WSDL file will use the snapshot name once you
select this option. You must generate the types again for business objects
(complex types) each time you create a snapshot for the inbound web
service.
4. Optional: Add a SOAP header by creating a new variable in the Variables tab of
type SOAPHeader or SOAPHeaders, then map that variable in the Data Mapping
tab under Properties. For detailed instructions, see Creating implicit SOAP
headers for outbound web service integrations. You can add a SOAP header to a
SOAP request, for example, to pass additional context information to the web
service.
5. Click the Security properties tab. Specify the type of security by selecting Use
Basic Security or Use Policy Set.
A. If you select Use Basic Security, specify the policy sets that are used by the
269
web service, and provide the user name and password. Specify the certificate,
encryption, and signature settings for both the client application and the web
service server. These settings ensure the integrity and confidentiality of the
messages that are exchanged with the web service.
B. If you select Use Policy Set, select the policy set and the policy binding from
the drop-down lists.Policy Set: Specifies the name of the application policy set.
Click Select to choose the policy set. The list you will see depends on the
policies available on the server. Some default application policy sets include:
WSHTTPS default, WSAddressing default, and Username WSSecurity default.
You can also create additional application policy sets in the WebSphere
Application Server Administrative Console. Deselecting a policy set also
removes the policy binding. More information on policy sets can be found in the
WebSphere Application Server Web Services Guide IBM Redbook.
Policy Binding: Specifies the name of the general client policy set binding,
which contains system-specific configuration parameters like username and
password information. Click Select to choose the policy binding. The list you
will see depends on the policy set bindings available on the server. Default
policy set bindings include: Client sample and Client sample V2. You can also
create additional policy set bindings in the WebSphere Application Server
Administrative Console. Deselecting removes the policy binding.
6. Configure the input and output mappings for the parameters in the WSDL file by
clicking the Data Mapping properties tab.
Parent topic:Creating outbound integrations to web services
Related information:
Supported web service standards
270
Description
Requires a user name and password.
IBM BPM never stores the password in
plain text in its database or export files,
and no plain text passwords are required
in IBM BPM configuration files.
Attention: The user name and password
are sent as base64-encoded text strings
in the HTTP basic authentication header.
To prevent eavesdropping, use only SSL
secured connections by ensuring that the
URL starts with https://.
For more information, see RFC 2627.
271
272
event
If you want to catch specific WSDL faults (those that match a particular fault name
or fault type), use the Catch Specific Errors option in the error intermediate event.
Use the following requirements when you define the WSDL fault:
- Specify a value for the name that begins with either an alphabetical character or
the underscore (_) character. Valid values can include alphabetical characters,
numbers, and the underscore. Names cannot contain words that are used within
IBM Business Process Manager (for example, arrayOf or listOf).
- When defining wsdl:part entries for the fault, use the element attribute in order to
comply with the WS-I Basic Profile specification.
The following example shows a web service that contains an error intermediate
event that is set to catch specific WSDL errors, such as multiCFaultFault1. You can
see the settings in the Error Properties section of Process Designer, as well as an
excerpt of the related WSDL file.
<wsdl:operation name="multiCFault">
<wsdl:input message="tns:multiCFaultRequestMsg" name="multiCFaultRequest"/>
<wsdl:output message="tns:multiCFaultResponseMsg" name="multiCFaultResponse"/>
<wsdl:fault message="tns:multiCFault_multiCFaultFault1Msg" name="multiCFaultFault1"/>
<wsdl:fault message="tns:multiCFault_multiCFaultFault2Msg" name="multiCFaultFault2"/>
</wsdl:operation>
273
After the web service integration discovers the WSDL file and generates the types
(the input and output variables needed for the service), the specified faults can be
caught when the web service runs.
274
Example
You are passing an object of type NameUpdateRequest as an argument to a web
service. This object is defined in the namespace
http://www.lombardisoftware.com/schemas/NameUpdateRequest . The
NameUpdateRequest object contains two properties, First (string) and Last (string).
Following is example code to generate the XML that is part of the SOAP call:
<# out = new tw.object.Record(); out.setSOAPElementNS("http://www.lombardisoftware.com/schemas/ NameUpdateRequest");
out.setSOAPElementName("NameUpdateRequest"); out.defineSOAPProperty("First", "http://www.w3.org/2001/ XMLSchema",
"string", false, ""); out.defineSOAPProperty("Last", "http://www.w3.org/2001/ XMLSchema", "string", false, ""); out.First
= "John"; out.Last = "Smith"; #>
275
<private-key>
<alias>soapprovider</alias>
<keyname>soapprovider</keyname>
</private-key>
<keystore-type>JKS</keystore-type>
<certificate>path to client certificate</certificate>
</webservice-security>
</server>
Description
Provide a name for the key
store file related to the
service requester.
276
Example
profile_root/etc/ws-
security/dsigsender.jks
<keystore-passwordencrypted>
<private_key>
<alias>
<keyname>
<password-encrypted>
<keystore-type>
<certificate>
KeyName : CN="Bob",
OU=IBM, O=US,.. or
KeyName : Bob
keystore-type="JKS"
{Install-Location}\client.cert
Procedure
1. Stop the deployment manager, process server, and Process Center server if they
are running.
2. Open the 100Custom.xml file in a text editor.
3. Uncomment the <server> section, and specify the encryption settings.
4. Specify the encryption settings.
5. Start the process server or the Process Center server.
Results
277
The encryption-related settings are now available for use in Process Designer for
Web Service integration step types.
What to do next
Specify the encryption settings on the Security tab for the Web Service integration
step type.
- Encrypt request
- Select this option to encrypt outbound SOAP messages. Note that you cannot
modify the parts of the message that are encrypted. The Web Service
integration step type always encrypts the SOAP body, the WS-Security
username token (if present), and the WS-Security signature (if present). With
this option, you also need to provide a value for the Server certificate alias in
order to configure the encryption key.
- Expect encrypted response
- Select this option to specify that you expect the web service provider to use
WS-Security message-level encryption in the response. Note that you cannot
modify the parts of the message that are encrypted. The Web Service
integration step type always assumes that the SOAP body and the WS-Security
signature (if present) are encrypted. With this option, you also need to provide a
value for the Client certificate alias in order to configure the decryption key.
278
Nonexistent host
279
Possible resolutions
You have incorrectly typed
the URI value. Navigate to
the URI using a web
browser to verify that you
have the correct WSDL. A
common problem is that
the ?wsdl argument is
missing from the end of the
URI.
For file protocol URIs, the
URI does not exist on disk.
If you are unable to
validate the location of the
URI on disk, contact your
network administrator.
You have incorrectly typed
the host value. Navigate to
the URI using a web
browser to verify that you
have the correct host
information.
The server that hosts the
URI is offline (not running).
Contact your network
administrator to determine
if this is causing the
problem.
The network is
experiencing connectivity
problems. Contact your
network administrator to
determine if this is causing
the problem.
280
281
Description
The anySimpleType type is not
supported.To fix the error,
replace anySimpleType with an
appropriate simple type.
282
283
Description
Process Designer does not
support attributes with default
or fixed values. These values
are ignored. To remove this
warning, if no corresponding
attribute is present in an
instance document, specify a
value for the attribute other than
default or fixed.
Process Designer does not
support using qualified or
QNames for types. The location
of the type is in XPath format.
Process Designer generates
different names for these types.
The base64Binary and
hexBinary data types have
validation rules that are
supported in Process Designer.
To prevent them from having
values that are not valid in
Process Designer, these data
types are converted to strings.To
remove this warning, do not use
the base64Binary and
hexBinary types.
284
286
Procedure
1. Open the Process Designer desktop editor.
2. Create an integration service.
3. Drag a Java Integration step from the palette to the service diagram and then
use sequence lines to connect the step to the Start and End Events.
4. Click the Java Integration step in the diagram and then click the Definition option
in the properties.
5. Click the Select button next to the Java Class field to choose the JAR file and
the class on the JAR file that you want to call.The JAR files listed are the ones
added as managed server files as described in topic "Managing external files".
By default, the classes in the IBM BPM Java package are available in the
integration.jar file, which is included in the System Data toolkit. If your
current project has dependencies on other toolkits that include JAR files, those
files are also available.
6. From the Discovery section (under the Properties and Definition tabs), click
the Method field. From the drop-down list, choose the method that you want to
call on the class that you selected in the preceding step.
7. Enable the Translate JavaBeans check box if you want the result of the Java
method that is invoked to be serialized and returned to the Integration service as
an XML element. The content of the element is based on the properties of the
object's class. For example, if you choose the teamworks.Users class from the
integration.jar file (IBM BPM Java packages) and then select the getUser
method with the Translate JavaBeans check box enabled. The result looks like
the following example:
<userino type="com.lombardisoftware.core.UserInfo" description="UserInfo">
<calendarId type="com.lombardisoftware.client.persistence.common.ID" description="calendarId" />
<fullname type="java.lang.String" description="String">tw_author</fullname>
<qualifiedName type="java.lang.String" description="String">tw_author</qualifiedName>
<sendToAddress type="com.lombardisoftware.core.routing.Address" description="Address">
<name type="java.lang.String" description="String">tw_author</name>
<toGroup type="java.lang.Boolean" description="Boolean">false</toGroup>
<toUser type="java.lang.Boolean" description="Boolean">true</toUser>
287
</sendToAddress>
<userData type="java.util.HashMap" description="HashMap">
<entry key="Full Name" description="Map Entry">
<key type="java.lang.String" description="String">Full Name</key>
<value type="java.lang.String" description="String">tw_author</value>
</entry>
<userData>
<userId type="com.lombardisoftware.client.persistence.common.ID$NumericID" description="ID$NumericID">
<id type="java.math.BigDecimal" description="BigDecimal">2</id>
<type type="com.lombardisoftware.client.persistence.common.POType$User" description="POType$User">
<deleted type="java.lang.Boolean" description="Boolean">false</deleted>
<exportable type="java.lang.Boolean" description="Boolean">false</exportable>
<factoryName type="java.lang.String"
description="String">com.lombardisoftware.client.persistence.UserFactory</factoryName>
<id type="java.lang.Integer" description="Integer">2048</id>
<libraryItem type="java.lang.Boolean" description="Boolean">false</libraryItem>
<name type="java.lang.String" description="String">User</name>
<tableName type="java.lang.String" description="String">LSW_USR_XREF</tableName>
</type>
</userId>
<username type="java.lang.String" description="String">tw_author</username>
</userinfo>
Note: When you enable the Translate JavaBeans check box, the variable type
that you select in the Integration service for the value returned from the Java
method should be XMLElement or ANY.
If you do not enable the Translate JavaBeans check box, the Java method can
only return objects of the types shown in Table 1.
Table 1. Types of objects returned by the Java method if Translate JavaBeans is
not enabled
Object types
java.lang.String
java.lang.Long
java.lang.Integer
java.lang.Short
java.lang.Byte
java.lang.Double
java.lang.Float
java.lang.Boolean
java.lang.Character
java.lang.Calendar
java.lang.ArrayList
java.lang.HashMap
org.jdom.Document
org.jdom.Element
com.lombardisoftwar
e.core.XMLNodeList
and
com.lombardisoftwar
e.core.TWObject
8. Click the Variables tab for the Integration service to add any input variables that
the service needs to receive and any output variables that the service needs to
make available for subsequent steps in the service or BPD.
9. Click the Java Integration step in the service diagram and then click the Data
Mapping option in the properties to configure the input and output mappings for
the step.
288
10. Nest the Integration service in another service or select it as the implementation
for an activity, depending on the requirements of the overall process.
Parent topic:Creating outbound integrations
Related information:
Creating, changing, and deleting a toolkit dependency in the Designer view
Building an Integration service
Managing external files
Using the TWObjectFactory, TWObject and TWList classes
289
Procedure
1. Open the Process Designer desktop editor.
2. Create an integration service.
3. In the Integration service, add a Java Integration component.
4. In the Variables tab, add an input variable with a Boolean value set to true. The
input variable instructs the SMTP server to use file names to identify attachments
instead of a full path name. For example, use a name like useFileName.
5. Create all the other variables to pass values to the SMTP server. Use them later
in the Data Mapping section.
6. On the Definition tab, select the teamworks.Mail class and the sendMessage
method that includes the Boolean parameter.
7. In the Data Mapping section, add the variables that are expected by the SMTP
server, including a variable for your attachments. In the Replace Full Paths By
File Names field, add the variable that you created earlier to indicate that you are
specifying the names of the files that are being transferred and that you are not
using the full path name for them.
Parent topic:Creating outbound integrations
290
The SQL Integration services are Java-based integrations that bind to a specific
method in the teamworks.SQLConnector Java class. Although you cannot alter the
SQL Integration services, you can open them in the Designer in IBM Process
Designer to see the method implemented by each one and the available input and
output variables as outlined in the following procedure.
Procedure
291
What to do next
To use a SQL Integration service in an implementation, you can:
- Select a SQL Integration service as the implementation for an activity as described
in Implementing activities in a BPD .
- Nest a SQL Integration service in another service by dragging it from the library to
the diagram of the parent service.
292
293
For general and introductory information, see Integrating with web services, Java
and databases.
The following sections describe how to create simple components so that you can
easily build the integration and also easily test your initial implementation.
References to more detailed descriptions of the implementation options for each
component are provided in the relevant sections.
Note: You can call an undercover agent (UCA) using another business process
definition (BPD), using a web service (and an associated caller service), or via JMS
as illustrated in this sample. To learn how to establish message flow between two
BPDs instead of using a service, see Using intermediate message events and
message end events to send messages and Using message end events.
- Adding a message event to a BPD
Start building the sample integration by adding a message event to a business
process definition (BPD).
- Creating an attached service
Create a service to pass parameter values from the message event to the
business process definition (BPD).
- Creating an undercover agent
Create an event-based undercover agent.
- Attaching the undercover agent to the message event
Attach the undercover agent (UCA) to the message event. The event waits for the
completion of the UCA. When the UCA completes, the event completes.
- Creating a caller service
Create a service with appropriate inputs to call the undercover agent (UCA) to
send the event.
- Creating an inbound web service
Create an inbound web service to provide a way for an external system or
application to call into IBM Business Process Manager.
- Testing the integration
Test the completed inbound integration using the Inspector.
Parent topic:Creating inbound integrations
294
Procedure
1. Open the Process Designer desktop editor.
2. Open a process application in the Designer view.
3. Create a simple BPD that contains two activities. (If you need detailed
instructions, see Creating a business process definition (BPD) .)
4. Drag an Intermediate Event component from the palette onto the BPD diagram so
that it falls between the two activities.
5. In the text box that displays over the event, type a name for the event. For this
sample, you can type: Incoming Message Event.
6. Click the Implementation tab in the properties. The default implementation for
intermediate events that are included in the process flow is Message.
7. If not already selected, click the drop-down list and choose Receiving from the
available message types.
8. Use the Sequence Flow tool to connect the BPD components as shown in the
following example:
9. Save your work.
Parent topic:Building a sample inbound integration
295
Procedure
1. Open the Process Designer desktop editor.
2. Open a process application that contains a BPD.
3. Create a General System service and name it My UCA Handler or something
similar. (If you need detailed instructions, see Building a General System service
.)
4. Use the Sequence Flow tool to connect the Start Event and End Event
components in the service diagram. Because this service is used to simply pass
values, you do not need to add any service components to the diagram.
5. Click the Variables tab.
6. Click the Add Input button and replace Untitled in the Name field with
someString.
7. Leave the variable type for the input variable set to String.
8. Click the Add Output button and replace Untitled in the Name field with
someString.
9. Leave the variable type for the output variable set to String.
10. Save your work.
Parent topic:Building a sample inbound integration
296
Procedure
1. Open the Process Designer desktop editor.
2. Open a process application in the Designer view.
3. Click the plus sign next to Implementation and then select Undercover Agent
from the list.
4. In New Undercover Agent, enter the following information and then click the
Finish button.
- Name: Type My UCA or something similar for the name.
- Schedule Type: Select On Event from the drop-down list.
5. In the Details section, the queue for processing this undercover agent is set to
Async Queue by default. This setting is fine for the sample integration. (To learn
more about the queue options, see Undercover agents.)
6. In the Parameter Mapping section, you can see that the undercover agent is
automatically mapped to the someString variable from the attached service, My
UCA Handler.
7. Save your work.
What to do next
Now that the undercover agent is available, you can attach it to the message event.
Parent topic:Building a sample inbound integration
Related information:
Undercover agents
297
Procedure
1.
2.
3.
4.
5.
6.
298
of 50 and another process application with the instance ID of 100, if you invoke
the UCA passing an ID of 50, only the first process application receives the
event.
10. Save your work.
Parent topic:Building a sample inbound integration
Related information:
Undercover agents
299
Procedure
1. Open the Process Designer desktop editor.
2. Open a process application in the Designer view.
3. Create an Integration service and name it Inbound WS Handler or something
similar. (If you need detailed instructions, see Building an Integration service.)
4. Drag an Invoke UCA component from the palette, name it My UCA and place it
between the Start Event and End Event in the service diagram.
5. Use the Sequence Flow tool to connect the service components on the diagram.
6. Click the Invoke UCA component in the diagram.
7. Click the Variables tab, and then click the Add Input button to add the
someString variable as an input variable.
8. Save the changes.
9. Select the Implementation option in the properties.
10. Click the Select button next to the Attached Undercover Agent field and pick the
Undercover Agent that you created in the preceding procedure, My UCA.
11. Select the Data Mapping option in the properties. The Input Mapping is
automatically set to the someString variable from the UCA.
12. In the field next to the variable, type tw.local.someString. This sets the input
value of the UCA to the local value of the someString variable, which enables
you to test the implementation in the Inspector as instructed in Testing the
integration. The value is used in the business process definition correlation
mapping that is created in the initial task. Note: The someString variable is
available only if you create the attached service as instructed in Creating an
attached service and the UCA as instructed in Creating an undercover agent
before performing the steps in this procedure.
13. Save your work.
Parent topic:Building a sample inbound integration
300
the endpoint URL, it points to the tip snapshot for Process Center, or to the default
snapshot for Process Server. If you want to invoke a web service for a specific
snapshot, make sure to specify the snapshot_name in the endpoint URL.
Procedure
1. Open the Process Designer desktop editor.
2. Open a process application in the Designer view.
3. Select the plus sign next to the Implementation category and then select Web
Service from the list.
4. In New Web Service, type KickTheBPD in the Name field and then click the
Finish button.
5. In the Operations section, click the Add button and select the Inbound WS
Handler Integration service that you created in the preceding procedure from the
list.
6. In the Operation Detail section, change Untitled in the Operation Name field to
doKick or something similar.
7. Notice the WSDL URI in the Behavior section. You can use this URI to test the
sample integration as instructed in Testing the integration.The Protected check
box adds user name and password security to an operation in the web service.
For a web service client to invoke a protected operation, the user ID and
password added to the user name and password elements for this operation must
be registered at the server, assigned to the process application and have at least
301
read authority. Note that this is not authentication in the context of an HTTP
transaction, so selecting Protected does not display a default user ID and
password.
The Target namespace scheme drop-down list provides options for setting the
target namespace:
- Per Process App/Toolkit settings (default): Uses the namespace from the
Advanced XML Settings section of the Process App Settings page and does
not include the snapshot name. This is the recommended setting as the target
namespace will remain consistent when using multiple snapshots. Note that the
namespace must be already set at the time of this selection or Per snapshot
name will be used. You will not be able to modify or update this value.
- Per snapshot name: Includes the snapshot name as well as the namespace
from the Advanced XML Settings section of the Process App Settings page,
if set. This scheme was used to define the target namespace before IBM BPM
8.0.1. The target namespace value in your web service client will be different
each time a snapshot is taken. You will not be able to modify or update this
value.
- Custom: Lets you create your own target namespace in the Target namespace
field.
Important: If you select Per snapshot name, the namespace of the Web
Services Description Language (WSDL) file will be changed in the following
cases. You must generate the types again for your inbound web service so that
your namespace is consistent with the namespace on the server.
- The inbound web service uses a business object defined in the System Data
toolkit. The namespace of that business object uses a host name and port
specification. You must generate the types again if the inbound web service's
host name and port are changed because of this situation.
- The Target namespace schema field is changed to the Per snapshot name
value. The namespace of the WSDL file will use the snapshot name once you
select this option. You must generate the types again for your inbound web
service each time you create a snapshot.
- The Target namespace schema field is changed to the Per snapshot name
value. The namespace of the WSDL file will use the snapshot name once you
select this option. You must generate the types again for your inbound web
service each time you switch the snapshot to the default or the non-default
version. Note: In this situation, if the inbound web service is defined in the
toolkit, the namespace of this WSDL file will not be changed when you switch
the snapshot to the default or the non-default version.
8. The Security and Policy section allows you to configure a policy set and a policy
binding with your web service. The server must have been already configured by
a system administrator.
- Policy Set: Specifies the name of the application policy set. Click Select to
choose the policy set. The list you will see depends on the policies available on
the server. Some default application policy sets include: WSHTTPS default,
WSAddressing default, and Username WSSecurity default. You can also create
additional application policy sets in the WebSphere Application Server
302
What to do next
If you do not specify a snapshot name in the URI, then the default track is used to
locate your web service. The tip in the default track is assumed to contain the
process application with your web service. However, if you have your web service
on a tip in a non-default track, it cannot be found. Therefore, create a snapshot
name or make the track that you are working with the default track.
303
Procedure
1. Open the Process Designer desktop editor.
2. Open a process application that contains the simple BPD that you created per
the instructions in Adding a message event to a BPD.
3. Open the BPD and click the Run icon in the upper right corner of the BPD
diagram. (If you need detailed instructions for using the Inspector, see Stepping
through a process.)
4. When IBM Business Process Manager prompts you to change to the Inspector
interface, click Yes. Note: Click the check box if you want IBM Process Designer
to change interfaces without prompting for approval.
5. From the Process Instances tab, click the received task for Step 1 and then
click the run icon ( ). The coach for the activity, which is the default Human
service, opens in a browser.
6. Click the Done button in the Coach to complete the first step.
7. Click the refresh icon ( ) in the toolbar. You can see that the process instance
is waiting for the incoming message event.
8. Using your SOAP utility, such as soapUI, point to the WSDL URI for the
KickTheBPD inbound web service that you created per the instructions in
Creating an inbound web service.
9. In your SOAP utility, initiate a request to the doKick method. In the someString
parameter for the method, provide the Instance ID for the currently active
instance, which you can see in the Process Instances tab in the Inspector. For
example, in the preceding image, the instance ID of the active instance is 4.
10. Click the Refresh icon in the Inspector toolbar. You should see that Step 2 has
been received, meaning that the message event was successfully processed
and the instance is able to move to the next step.
11. Click the Step 2 task to select it and then click the Run task icon. The value is
used in the business process definition correlation mapping that is created in the
initial task. If this value and the value of the BPD mapped variable are equal, the
message intermediate start event runs. If not, the message intermediate start
event continues to wait until a match is found.
304
12. The Coach for the activity, which is the default Human service, opens in a
browser. Click the Done button in the Coach to complete the second step.
13. Click the Refresh icon in the Inspector toolbar. You should see that the task for
Step 2 is closed and the process instance has a status of Complete, indicating
that the BPD instance has completed successfully.
Parent topic:Building a sample inbound integration
305
306
Procedure
To retrieve SOAP headers from an inbound SOAP request message, write
JavaScript code that uses the tw.system.header.soap.request system variable.
You can add a component, such as a server script component, to your general
system service. You can then add your JavaScript code to this component's
Properties view within the Pre-execution or Post-execution Assignments section or
within the Implementation section. Alternatively, you can add the code to any
location that is part of the general system service for the endpoint. In this example,
the code example is retrieving a header named subscriptionInfo of type
SOAPHeader from the system variable tw.system.header.soap.request. If the
request message contains SOAP headers, this variable will be initialized to contain
them. If the request message does not contain SOAP headers, this variable will be
null.
log.info(">>>>>> Checking to see if the subscriptionInfo SOAP header was received in the request message...")
if (tw.system.header.soap.request != null) {
for (var i = 0; i < tw.system.header.soap.request.headers.listLength; i++) {
// search for the subscriptionInfo header
if (tw.system.header.soap.request.headers[i].name == "subscriptionInfo") {
subscriptionInfoHeader = tw.system.header.soap.request.headers[i]
}
}
}
if (subscriptionInfoHeader != null) {
log.info("Found the subscriptionInfo SOAP header!")
}
307
else {
log.info("The subscriptionInfo SOAP header was not present in the request message.")
}
header!
Parent topic:Creating implicit SOAP headers for inbound web service integrations
308
Procedure
To add a SOAP header to an outbound response message, add an entry to the
SOAPHeaders array within the tw.system.header.soap.response system variable.
You can add the code to the Pre & Post > Post-execution Assignments section
within a component of a general system service, such as a server script component.
To add a header that is called sessionToken to the response message, use
JavaScript code such as the following example. Follow these best practices as you
write your code:
- Make sure namespaces are fully qualified, as they are in the following examples.
- Avoid white spaces in the XML snippet that constitutes the SOAP header value.
- Make sure that you only instantiate the tw.system.header.soap.response
variable if it is null. Otherwise, you could end up clearing out SOAP header entries
that were added by some other component within your general system service.
log.info(">>>>>> Adding a SOAP header to the response message...")
// Determine which index we need to use when adding the new header entry.
//Add the new header at the end of the array so that the processing does not
// overwrite any existing entries.
var nextIndex = tw.system.header.soap.response.headers.listLength
309
Note: Use the next available index when adding your new SOAP header entry to the
tw.system.header.soap.response variable "headers" field, which is an array of
SOAP header values. Otherwise, you might inadvertently clear out an existing
SOAP header entry that was added by some other component within your general
system service.
Parent topic:Creating implicit SOAP headers for inbound web service integrations
310
If you do not include the snapshot name in the message, the Event Manager uses
the default snapshot on the target Process Server for start message events. For
intermediate message events, if you do not include the snapshot name in the
message, all active snapshots receive events. To learn more about active and
default snapshots, see Configuring runtime settings for installed snapshots. Note: If
the value of the <value> element contains XML elements or similar content, you
need to wrap the value in a CDATA tag as shown in the preceding example. For
information about passing parameter values for each complex business object
(variable type), see the following section.
Syntax
XMLDocument
XMLElement
XMLNodeList
311
Map
ANY (default)
For example, to invoke an undercover agent using an XML message, let's say your
runtime process contains a message event that waits for an incoming message.
This message contains an input parameter whose value includes the Customer
Name, Description, and Age.
First, create the service and then associate the service with an undercover agent
(the service describes what happens when the undercover agent is invoked at run
time). Then, send the message with the following syntax:
<eventmsg> <event processApp="[acronym]" snapshot="[snapshot_name]" ucaname="[UCA_name]">[event name]</event>
<parameters> <parameter> <key>customerParam</key> <value> <Name>John</Name> <Description>John Description</Description>
<Age>30</Age> </value> </parameter> </parameters> </eventmsg>
The following sections provide examples of how to pass the content of the <value>
element. The conversion from the event XML format to a complex type is handled
automatically by the IBM BPM engine.
When the Any type is used to pass a parameter value, the actual IBM BPM type
must be supplied using the type attribute of the corresponding element. The type
attribute can be omitted only when IBM BPM knows the exact type or when the type
is String. The value of the attribute must be an existing IBM BPM type-or in case of
an array, an IBM BPM type concatenated with the [] string at the end.
Passing array properties: Every object in the object array is converted to XML
using the object property name as an XML Element name. For example:
<value> <Name>John Doe</Name> <Description>Single</Description> <Age>30</Age> <Address> <Street>10506 Jollyville
Rd</Street> <City>Austin</City> </Address> <Address> <Street>10507 Research Blvd</Street> <City>Austin</City>
312
</Address> </value>
Because all values and keys in this case need to be of the ANY type, the type
information must also be passed in order for the correct objects to be instantiated
during deserialization. If the object is of the String type, the type does not need to
be specified.
313
314
Procedure
1. Open the Process Designer desktop editor.
2. Open a process application in the Designer view.
3. Select the plus sign next to the Implementation category and then select Web
Service from the list.
4. In the New Web Service window, type a name for the service and then click the
Finish button.
5. In the Common section, you can type a description of the web service in the
Documentation text box.
6. In the Operations section, click the Add button to choose an existing service to
add. Because the services that IBM BPM initiates from a web service do not
have an associated task, do not add services that include the following
components: Coach, Modify Task, and Browser Script. See Service components
in Process Designer for more information about these components.
7. Under Operation Details, type a name for the selected service in the Operation
Name text box. (Change Untitled to the name that you want.)
8. Optionally, you can type a description of the operation in the Documentation text
box.
9. Click the Add button in the Operation section to continue adding services.
10. In the Behavior section, enable the Protected check box if you want access to
the WSDL URI to be password-protected. If password-protected, a user must
supply a user name and password to access the operations described in the
WSDL URI.
11. In the Behavior section, click the WSDL URI to view the XML description of the
resulting web service and its elements and operations. You can supply this URI
to the developers who need to call the operations within the web service.
12. Include a message event in your BPD for the incoming request as described in
Modeling events.
315
13. Create an undercover agent that calls this web service as described in
Undercover agents and then attach the undercover agent to the event from the
preceding step.
What to do next
Note: When you install a process application on a test or production server, all web
services are included in the list of exposed items in the Process Admin Console.
316
317
Procedure
1. Verify that you have a live WSDL URL.
2. Paste the URL into a browser window. You may need to add ?WSDL to the end
or your URL. If the URL is not working, you are likely lacking the correct network
configuration to access the web service.
3. Install soapUI using the default configuration.
4. Right-click Projects and click New soapUI Project.
5. Paste your WSDL URL into the box labeled Initial WSDL/WADL. Do not change
the other values and options and click OK. You should now have a sample call
for your web service where you can make sample calls based on XML input.
6. Test the web service by replacing question marks with actual data inputs and
press Play. There are hints that are provided by soapUI in places where repeated
entries or optional entries exist. For these entries, deleting items should not be a
problem.
Parent topic:Web services compatibility
318
Procedure
1. Open the Process Designer desktop editor.
2. Open a process application in the Designer view.
3. Click the plus sign next to the Implementation category and select
Implementation Service.
4. In the dialog that opens, enter a name and click Finish.
5. Beneath TOOLKITS, expand SystemData and select Implementation. Locate
the Call WebService via SOAP component and drag it onto the diagram.
6. Drag a Server Scriplet from the right-side palette to your diagram. Place it to
the left of Call WebService via SOAP.
7. Connect the lines. Start should connect to the Untitled server scriptlet. The
Untitled server scriptlet should connect to Call WebService via SOAP. Call
WebService via SOAP should connect to End.
8. Select the Call WebService via SOAP component. Select the Data Mapping
tab in the Properties view. You should be able to identify all of the inputs
required except for the request input.
- wsdlURL maps to the URL address.
- serviceNS maps to the targetNamespace value.
- serviceName maps to the service name value.
- destinationAddress maps to the soap:address location value.
- soapAction maps to the soap:operation soapAction value.
9. The request input includes your variable inputs. In this example, we use the
server scriptlet to create the XML input.
A. Open the variables tab and create a new private variable called request with
an XMLElement type.
B. Return to the diagram view and rename the server scriptlet to Set Request.
C. Select the Implementation tab from the Properties view for the server
scriptlet and bind the implementation to your request variable. Click Select
and click the request variable from the menu.
D. Copy your entire XML input from soapUI and paste it into the server scriptlet
implementation.
319
E. Bind your request variable to the request input of the SOAP Connector.
Return to the Data Mapping section of the Call Web Service via SOAP
component and, using Select, map request (XMLElement) to the request
variable you just created.
10. In a similar manner, create a variable called response of type XMLElement,
and bind it to the output of the SOAP Connector; that is, the Call Web Service
via SOAP component. At this point, you should be able to test your service
using hard-coded values.
11. Run the service in debug mode to see the response placed into your response
variable. If it worked correctly, you are ready to add input variables to your
service and map them into your request variable in the server scriptlet. The
following example only has one input:
A. Add an input variable to your service.
B. Use <#= #> notation to include JavaScript in your server scriptlet. For
example if your input variable was degreesF. the implementation code
referring to it would be <# = tw.local.degreesF #>. Now your service input
will determine the input to the SOAP Connector.
12. Use Xpath to map your response variable into proper outputs. This example
uses a single output variable (_degreesC).
A. Add a Server Script to the end of your service
B. Use Xpath to map the XML response into the output variables. For example:
1. This Xpath expression returns a node list of all 'Page' nodes until the
VisioDocument/Pages node:xml.xpath("VisioDocument/Pages/Page");
You might need to experiment with having or not having a slash at the
beginning depending on the structure of the XML.
2. This Xpath expression returns a node list of all 'Master' nodes that have the
NameU attribute equal to 'Horizontal holder':
xml.xpath("VisioDocument/Masters/Master[@NameU='Horizontal holder']");
3. In either case, you need to know the node path and namespace. The
following Xpath expression ignores the depth and ignores namespaces. It
is the same as i, except it ignores namespace and depth of 'Page' node:
xml.xpath = "//*[local-name()='Page']";
In any case, the result is a nodelist that can be used something like: var
nodeList = xml.xpath(...);
tw.local.objArray = new tw.object.listOf.myObj();
for (var i=0;i<nodeList.length;i++) {
var obj = new tw.object.myObj();
//If name node always exists as a child
obj.name = nodeList[i].name[0].getText();
tw.local.objArray[tw.local.objArray.listLength] = obj;
}
320
321
322
Procedure
1. Select the Servers tab from the Process App Settings editor. You will see the
Process App Settings editor when you first click Open in Designer from a
newly created process application in the Process Center. Alternately you can
select Process App Settings from the drop-down list on the toolbar in Process
Designer.
2. Beneath the Servers heading click Add. Beneath the Server Details heading,
enter a meaningful name for server. From the drop-down list in the Type field,
select IBM Case Manager Server. Enter a description of what the server does or
provides in the Description field.
3. Beneath the Server Locations heading, enter the following information.
- Environment Type: The environment of the IBM Case Manager server. Enter
the server location information (hostname, port, if it will be a secure service,
target object store, connection userid and password) for each environment type.
If you do not provide values for these environments, the values from the default
environment type will be used.
- Default: A set of default values that are used if you do not provide values for
the following environment types.
- Development: The environment where you develop your services.
- Test: The environment where you test your services.
- Staging: The environment where you deploy your services for pre-production
testing.
- Production: The environment where your services are deployed for use by
your organization.
- Hostname: The hostname of the IBM Case Manager server. Specify an IP
address or a hostname and domain (but do not specify http:// or another
protocol). For example:myHost.labwide.ibm.com
- Port: The port number of the IBM Case Manager server.
- Secure: Select if you want your service to be secure, that is, use the Hypertext
Transfer Protocol Secure (HTTPS) protocol. If you are accessing a server using
SSL security, see Accessing an IBM Case Manager server using the Secure
Sockets Layer (SSL).
- Target Object Store: The target object store name for the IBM Case Manager
server. A target object store is used to store runtime case solutions. If you do not
know the name, you should be able to get it from the IBM Case Manager server
administrator.
323
- Connection Userid: The userid for connecting to the IBM Case Manager
server.
- Password: The password of the userid connecting to the IBM Case Manager
server.
4. Save your work. From the menu, select File > Save All.
Parent topic:Integrating BPDs with IBM Case Manager cases
324
Procedure
1. Open the Process Designer desktop editor.
2. Open a process application in the Designer view.
3. Click the plus sign next to Implementation and select IBM Case Manager
Integration Service from the menu to create a service that the business
process could use later. The library section is found in the upper left area of
Process Designer. Enter a name for the service on the following dialog box and
click Finish. The IBM Case Manager Integration Service editor opens with the
Diagram tab in focus.
4. From the palette, drag an IBM Case Manager Integration step onto the canvas.
The initial IBM Case Manager Integration step is named Untitled which you
can rename to something more appropriate.
5. Click Implementation in the Properties view. Under IBM Case Manager
Server, select a case management server from the list of known servers. The
drop-down list of servers is located in the Server field. These servers are initially
defined under Process App Settings (see Adding an IBM Case Manager server
). Should there be no entries in the list that means that no servers have been
specified. Click Use Process Application Settings to add a server and add a
server.
6. Under Case Operation, select the appropriate operation.
- Create case: This operation lets you create a new case. A case is an instance
of a case type.
- Search case: This operation retrieves a set of case references according to a
query. See Building a query for a search case operation. The case references
are returned in an array object.
- Retrieve case: This operation retrieves a case, that is, a case instance, based
on a case reference. It can be used with a search case operation which
325
326
Procedure
1. In the IBM Case Manager editor, click the Case Filters tab.
2. In the left column, select the search node you want to create your query for, if you
created more than one search service.
3. Beneath Build Case Filter complete the fields appropriate to your query.
- Use Mapping Variable (String): Select this check box only if you are
experienced in writing Content Management Interoperability Services (CMIS)
queries and want to write your own hand-coded query (see the query section of
the CMIS specification for information on the syntax). You can improve your
response time by qualifying your SELECT clause as follows: SELECT
CmAcmCaseIdentifier, cmis:objectId FROM ...The case type in your query
takes precedence over the case type specified in your service. If there is a
difference between the case type in your query and the case type in your
service, the case type in your query will be used.
Selection will disable the fields in case filter and make the Input Mapping field
editable. Select the Data Mapping tab in the Properties view to see the Input
Mapping field.
- Match criteria: Lets you select all or any as a match criteria. All returns cases
matching all the criteria specified in the case filter. Any returns cases matching
any single field in the case filter.
- Case ID: Lets you specify a case.
- Case State: Lets you specify the state of a case: working, complete or failed.
- Date added between: Lets you specify a period of time when a case was added
to the case management solution.
- Added by: Lets you specify a userid that added a case.
- Date modified between: Lets you specify a period of time when a case was
modified.
- Modified by: Lets you specify a userid that modified a case.
- User-specified properties: Lets you specify custom properties found in the
case type selected for the node.
4. Save your work. File > Save All.
Parent topic:Integrating BPDs with IBM Case Manager cases
327
Procedure
1. In the IBM Case Manager Integration Service editor, create a flow of operations
similar to the following screen capture.
2. In the Loop Case References component, add JavaScript similar to the following
in the Implementation section of the Properties view. It will let the loop run until
there are no more cases in the array to process. /* Assumes that the counter variable will
always be reset to -1 at the end of the loop */
tw.local.counter ++; /* Increase the counter by one */
tw.local.currentReference = null; /* Reset the current reference */
/* If the counter is within the length of the array, get the next case reference */
if(tw.local.counter <= tw.local.references.listLength){
tw.local.currentReference = tw.local.references[tw.local.counter];
}else{
/* Else, reset the counter.
The Reference is
328
3. In the Implementation section of the Properties view for the Decision Gateway
, return the flow to the Update Case service when the currentReference
variable from the JavaScript shown previously is not equal to a null value.
4. Create a query to run against your IBM Case Manager solution as shown in
Building a query for a search case operation.
5. Run the business process that invokes this service.A different situation to the one
described in the previous steps is if you update a case instance in IBM Process
Center that originated on the IBM Case Manager server. When you return that
case instance to the IBM Case Manager server, use the
tw.system.enclosingCaseInstance system variable as the reference to the
case instance running on the IBM Case Manager server. This variable is only
available at the business process definition level.
Parent topic:Integrating BPDs with IBM Case Manager cases
329
330
331
Procedure
1. Launch the Administrative console and log in to the IBM Integration Solutions
Console of the server running your IBM Process Center.
2. For stand-alone servers, navigate to Security > SSL certificate and key
management > Key stores and certificates > NodeDefaultTrustStore >
Signer certificates. In a Network Deployment (ND) environment, the truststore is
called CellDefaultTrustStore.
3. Click Retrieve from port.
4. In the Host field, enter the hostname, in the Port field enter the secure port
number and in the Alias field enter an alias name for the IBM Case Manager
server you want to connect to.
5. Click Retrieve signer information. Verify that the retrieved information is the
expected signer certificate of your Case Manager server. Click Ok if the retrieval
is successful.
6. In a Network Deployment (ND) environment, make certain all nodes are
synchronized. Save your work and log out of the IBM Solutions Console.
7. When you add this secure server in your process app settings page, use the host
name and port that you used in the IBM Solutions Console. Click the Secure
check box.
Parent topic:Integrating BPDs with IBM Case Manager cases
332
333
334
Procedure
1. Open the Process Designer desktop editor.
2. Open the BPD in the Designer view.
3. Click the Overview tab.
4. In the Exposing section, configure the exposure settings to expose different
aspects of the process to specific teams.Table 1. Settings that can be enabled in
the Exposing section
Exposure setting
Expose to start
Action
Click the Select button to choose the
team whose members can start
instances of this process in IBM
Process Portal. Members of the
selected team can start instances of the
process from the Launch tab in IBM
Process Portal.
Click the Select button to choose the
team whose members can perform ad
hoc analysis on this process in the Ad
Hoc Reports dashboard in IBM Process
Portal. The Ad Hoc Reports dashboard
is not exposed by default for Process
Portal users. If you want process
participants to see the Ad Hoc Reports
dashboard in their tabs list, you must
expose it manually. See Exposing the
Ad Hoc Reports dashboard.
Click the Select button to choose the
team whose members can view data for
this process in the Process
Performance dashboard in IBM Process
Portal.
To remove an assigned team, click the X icon next to the exposure setting.
335
5. Save your changes. Exposed BPDs and data from the current working version
are always available in IBM Process Portal. However, If you want exposed BPDs
and data from a particular snapshot to be available in IBM Process Portal while
under development on the Process Center Server, you need to activate the
snapshot (version) that you want. Anyone with administrative access to the
process application can activate snapshots. When you deploy snapshots of
process applications on Process Server in other environments, such as test and
production environments, those snapshots are active by default.
- Exposing the Ad Hoc Reports dashboard
If you want IBM Process Portal users to see the Ad Hoc Reports dashboard so
that they can generate dynamic reports directly from IBM Process Portal, you must
expose the Ad Hoc Reports dashboard manually.
Parent topic:Configuring a role-based business user interface
Related information:
Creating a team
Activating snapshots for use with IBM Process Portal
336
Procedure
1. Open the Process Designer desktop editor.
2. Open the process application in the Designer view and click User Interface.
3. In the library, go to User Interface > Heritage Human Service and open the Ad
Hoc Reports dashboard that you want to expose.
4. Click the Overview tab.
5. In the Exposing section, click Select next to the Exposed to field to choose the
team whose members can view and use the exposed Ad Hoc Reports dashboard.
To create a team, click New. To remove an assigned team, click the X icon next
to the Exposed to field.
6. Save your changes.
Parent topic:Exposing business process definitions
337
Procedure
1. Open the Process Designer desktop editor.
2. Open the heritage human service that you want to expose and click the Overview
tab.
3. In the Exposing section, click Select next to Exposed to to choose the team
whose members can view and use the exposed service. To create a team, click
New. To remove an assigned team, click the X icon next to New.
4. In the Expose As list, specify the exposure type by selecting one of the following
options.Table 1. Exposing options
Option
Description
Do Not Expose (Service contained in a Use this default option for services that
BPD)
implement the activities within a BPD.
When this option is selected, the
Exposed to setting is not used.
Administration Service (Available in the Use this option to make the heritage
Process Admin Console)
human service available to members of
the selected team as a separate page in
the Process Admin Console in the
Server Admin capabilities. A new
category is added to the menu, which
has the same name as the process
application that contains the service.
The name of the individual page in the
new category matches the service
name.
Startable Service (Launch from Process Use this option to enable members of
Portal)
the selected team to start the service
from the Launch sidebar in Process
Portal.
338
Dashboard (Available in Process Portal Use this option to make the heritage
Dashboards menu)
human service available in Process
Portal to members of the selected team.
Team members can access the
dashboard by clicking the Organize
tabs icon , and selecting the
dashboard from the list of hidden
pages. If you do not specify a
localization resource for the dashboard
name, the dashboard page has the
same name as the exposed service.
If you defined a localization resource for
your dashboard name, click Select next
to the Label field and select the key in
the resource. See Globalizing
dashboard names.
If the heritage human service is in a
toolkit, you must complete the following
steps:Create a snapshot of the
toolkit.Activate the toolkit snapshot. See
Activating snapshots for use with IBM
Process PortalAdd the toolkit snapshot
as a dependency to a process
application. See Creating, changing,
and deleting a toolkit dependency in the
Designer view.
If you want to expose the dashboard
outside of Process Portal, generate a
portlet that you can deploy to a portal
server by clicking Create a Portlet
from the Dashboard.
URL (Available from a URL only)
Use this option to make the service
available from a URL address. For
information about the REST API that
provides the URL for the exposed
service, see REST Interface for BPDrelated Resources - Exposed Items
Resource.
Results
In addition to being exposed to user interfaces as described in the previous table, all
exposed heritage human services are made available to be called as URLs.
The URL is composed of the name of the host on which IBM Process Center Server
or Process Server is installed, the port that is designated for the server during the
IBM Business Process Manager installation, and the acronym for the process
application that contains the service. For example, if you expose a service named
MyService, you can access it from the following URL: http://host_name:port/contextRootPrefix
/executeServiceByName?processApp=acronym&serviceName=MyService
The default value for the contextRootPrefix is teamworks. For more information
about how to configure a custom context root, see the section for the -update
parameter in the BPMConfig command-line utility topic.Remember: Any browser339
specific URL limitations, such as the URL length and character restrictions, apply
and must be considered when calling a heritage human service as a URL.
- URL parameters
- The URL can contain one or more of the following parameters:
- processApp
- Date/Time syntax
- The date and time format differs between client-side human services and
heritage human services. The syntax for the other simple types (String,
Integer, Decimal, Selection) is the same for client-side human services and
heritage human services.
- Note: For information about the date and time syntax in human services, see
Exposing client-side human services.
- For heritage human services, the date and time format is as follows:
- The Date format is YYYY-MM-DD.
- The Time format is HH:mm:ss.
- Time Zone: Because support for time zone information is not provided with
heritage human services, the default time zone is set to the time zone of the
340
server.
- Service version invoked
- If a specific snapshot name is not passed to the URL, the default version of the
service that is run depends on the environment in which the service is running.
Table 2. Version of the heritage human service invoked for each environment
Environment
Process Center
Process Server
Process Portal
341
342
Procedure
343
To enable resumable dashboards for a process application, you must configure the
com.ibm.bpm.social.zResumable property:
1. Open the administrative console and click Resources > Resource Environment
> Resource Environment Provider > Mashups_ConfigService > Custom
properties.
2. Create a property named com.ibm.bpm.social.zResumable and set its value to
be a list of process application IDs, for example: TRD,RD,MAILCOM.
3. Save your changes
4. Restart the server. Important: Do not add the Process Portal (TWP) process
application to the com.ibm.bpm.social.zResumable list. The dashboards
delivered in the Process Portal application are not designed to be resumable.
5. Invoke resumable services by using the following URL: http://host_name:port/
contextRootPrefix/executeServiceByName?processApp=acronym
&serviceName=MyService. The default value for the contextRootPrefix
is
teamworks. For more information about how to configure a custom context root,
see the section for the -update parameter in the BPMConfig command-line utility
topic.
6. In addition to the standard service URL parameters, you can use the following
resumable parameters:
- zResumable=true
- If you use the URL to launch the dashboard as part of an application that
runs outside of Process Portal, you can use this parameter to override the
zResumable=true parameter so that a new dashboard instance results. If
you use this parameter, you must ensure that services are terminated, for
example, by modeling an end event in the service, or by calling an API to
complete or terminate the service.
- [zClientHandle={key}]
- If you use the URL to launch the dashboard as part of an application that
runs outside of Process Portal, you can use this optional parameter with the
zResumable=true parameter. With these parameters, you can use a clientside key as a reference to resume and reference multiple dashboard
instances.
For information about HTTP session settings including session timeout intervals,
see Session management settings in the IBM WebSphere Application Server
documentation.
Parent topic:Exposing heritage human services
344
345
Procedure
1. Define a new resource bundle group in Process Designer.
A. In the library for your process application, hover over Setup and click the Add
icon. In the window that opens, select Localization Resource. The New
Localization Resource wizard opens.
B. Enter a name for the resource bundle.
C. Add localizations and localization keys to the resource bundle group.
D. Save your changes.
2. On the dashboard Variables tab, link the resource bundle group to your
dashboard.
A. Click Link Localization.
B. Select the resource bundle group that you created in the previous step.
3. On the human service Overview tab, click Select next to the Label field. Select a
localization key from the resource bundle group that you want to apply to the
dashboard label.
Parent topic:Exposing heritage human services
Related information:
Customizing the IBM Business Process Manager dashboards
346
347
that is part of the heritage human service. The payload variable must be included
on each coach that is part of the heritage human service that is exposed as a
dashboard and deployed as a portlet. However, a coach can include a variable
without displaying it to process participants if you add a field for the variable to the
coach and set the visibility of the field as None (hide or disable).
- For globalization support for the name and description of the generated portlets,
make sure to prepare an XML file that you designate when you create the portlet
from the dashboard. The XML must be ready before you start the Export
Dashboard wizard. Ensure that the XML uses the same format as the following
example:<?xml version='1.0' encoding='UTF-8' ?>
<portlet>
<description xml:lang="en">English description</description>
<description xml:lang="fr">French description</description>
<description xml:lang="es">Spanish description</description>
<display-name xml:lang="en">English display name</display-name>
<display-name xml:lang="fr">French display name</display-name>
<display-name xml:lang="es">Spanish display name</display-name>
</portlet>
Ensure that the XML file has encoding defined as UTF-8. The XML file can contain
zero or more description or display-name elements. The description and
display-name elements cannot have empty string values. The xml:lang attribute
must follow the RFC 1766 specification, which is available at
http://www.ietf.org/rfc/rfc1766.txt.
- The collaboration feature is not available for dashboards exposed as portlets. That
is, users cannot interact in an activity with other users or experts like they can in
Process Portal.
- Using the same security protocol for both the IBM BPM server and the IBM
WebSphere Portal server prevents an issue where Process Portal users see a
blank task completion view in an IBM WebSphere Portal portlet. For example, use
HTTPS for both the IBM BPM server and the portlet running on the IBM
WebSphere Portal server, or use HTTP for both the IBM BPM server and the
portlet running on the IBM WebSphere Portal server. When you configure the
portlet on the IBM WebSphere Portal server and specify the IBM BPM URL,
specify the same security protocol that is used by the IBM BPM server.
Procedure
1. For heritage human services that are exposed as dashboards for a group of
process participants, click Create a Portlet from the Dashboard on the overview
348
Portal with a WSRP provider, see Using WSRP services on the IBM WebSphere
Portal wiki.
If you are not using WSRP, give the .war file to the portal server administrator to
deploy.
Discuss the following points with the portal server administrator:
- The administrator should install dashboard portlets on the same cluster as
Process Portal.
- Notify the administrator that the IBMBPM keyword is added to the generated
dashboard portlet. The keyword makes it easier for administrators to find and
manage the dashboard portlets.
- Make sure that the administrator knows that portlet preferences can be edited in
WebSphere Portal using the edit page for the portlet. The administrator can edit
the following information for the dashboard portlet that is generated: host name,
port number, width, and height.
- Give the administrator information about the following IBM BPM portlet
preferences that can be edited in the dashboard portlet. All other IBM BPM
portlet preferences should not be changed.
- bpmHost (default: localhost) - The host name or IP address for the server
- bpmPort (default: 9080) - The port number for the server
- bpmUseSSL (default: false) - The indication that https should be used instead of
http
- bpmWidth - The width (in pixels) to be used for the portlet iframe that displays
the dashboard
- bpmHeight (default: 400) - The height (in pixels) to be used for the portlet
iframe that displays the dashboard
- bpmUseDojo (default: true) - A boolean value to indicate if Dojo should be used
when available for client-side events. If the value is true, the portlet tests if Dojo
is loaded and uses the Dojo publish-subscribe methods to send and receive
events. If the value is false, the portlet uses server side-events as specified in
JSR286.
Tip: The WSRP Producer for WebSphere Application Server is a stateless
producer and does not manage any portlet preferences on the server. If you are
using the WSRP Producer, you must update the portlet.xml file that is
contained in the exported .war file with any portlet preference changes before
the administrator installs the .war file.
- Tell the administrator the following requirements for using single-sign-on (SSO)
and Secure Sockets Layer (SSL) protocol in WebSphere Portal with the
dashboard portlets from IBM BPM.
- To prevent the Process Portal login panel from appearing in the dashboard
portlet, administrators should enable and configure single-sign-on for the
WebSphere Portal and IBM BPM servers. See Single sign-on for
authentication in the WebSphere Application Server information center.
- To avoid browser messages about secure connects for process participants
who connect to WebSphere Portal and use the dashboard portlets,
administrators should replace personal, self-signed certificates with those
provided by a trusted external certificate authority (CA). See Creating a
certificate authority request in the WebSphere Application Server information
center.
350
351
Procedure
To expose a client-side human service, complete the following steps:
1. Open the Process Designer desktop editor.
2. Open the client-side human service that you want to expose and then click the
Overview tab.
3. In the Exposing section, in the Expose as list, specify the exposure type by
selecting one of the following options.Table 1. Exposing options
Option
Description
Do Not Expose (Service contained in Use this default option for client-side
a BPD or case type)
human services that implement
activities within a BPD or a case type.
When this option is selected, the
Expose to start setting is disabled.
Startable Service (Launched from
Use this option to enable members of
Process Portal)
the selected team to start the client-side
human service from the Launch sidebar
in Process Portal.
352
Dashboard (Available in the Process Use this option to make the client-side
Portal Dashboards menu)
human service available in Process
Portal to members of the selected team.
Team members can access the
dashboard by clicking the Organize
tabs icon
and selecting the
dashboard from the list of hidden
pages. If you do not specify a
localization resource for the dashboard
name, the dashboard page has the
same name as the exposed service.If
you defined a localization resource for
your dashboard name, click Select next
to the Label field and select the key in
the resource. See Globalizing
dashboard names.
If the client-side human service is in a
toolkit, you must complete the following
steps:Create a snapshot of the
toolkit.Activate the toolkit snapshot. See
Activating snapshots for use with IBM
Process PortalAdd the toolkit snapshot
as a dependency to a process
application. See Creating, changing,
and deleting a toolkit dependency in the
Designer view.
URL (Available from a URL)
Use this option to make the service
available from a URL address. For
information about the REST API that
provides the URL for the exposed
service, see REST Interface for BPDrelated Resources - Exposed Items
Resource.For fast access, the URL is
displayed as a link that you can either
click or copy and paste into your web
browser. To copy the URL, right-click
the link and select the option provided
by your browser to copy the URL (for
example, Copy Link Location in
Mozilla Firefox or Copy link address in
Google Chrome).
353
For client-side human services, the URL can include the following additional
parameters.Remember: Any browser-specific URL limitations, such as the URL
length and character restrictions, apply when a client-side human service is called
as a URL.
- Input variables
- In the URL, input variables that are defined for the service have the following
format:&tw.local.variableName=value
- Date/Time syntax
- The date and time format differs between client-side human services and
heritage human services. The syntax for the other simple types (String,
Integer, Decimal, Selection) is the same for client-side human services
and heritage human services.
- Note: For information about the date and time syntax in exposed heritage
human services, see Exposing heritage human services.
- For client-side human services, the date and time format is specified by
a profile of the ISO-8601 standard, as defined by RFC3339.
- The Date format is YYYY-MM-DD.
- The Time format is [hh]:[mm]:[ss], where
- [hh] specifies a zero-padded hour between 00 and 24 (where 24
indicates midnight at the end of a calendar day).
- [mm] specifies a zero-padded minute between 00 and 59.
- [ss] specifies a zero-padded second between 00 and 60 (where 60
indicates an added leap second).
For example, the time might be displayed as 13:47:30.
- Note the following time zone designators for Time:
- If no UTC relation information is given with a time representation, the time,
<time>, is assumed to be the local time. The <time>Z parameter refers to
UTC time. For example, 14:45:15 UTC can be 14:45:15Z.
354
- The following parameters are time zone offsets from UTC time:<time>hh:mm
<time>hhmm
<time>hh
For example, the following times refer to the same moment: 18:30Z,
22:30+04, 1130-0700, and 15:00-03:30.
- The combined Date and Time format is <date>T<time>, for example 200704-05T14:30Z or 2007-04-05T12:30-02:00.
4. Click Select next to Expose to start to choose the team whose members can
view and use the exposed service. To create a team, click New. To remove an
assigned team, click the X icon next to New.
Results
The default version of the exposed service that runs depends on the environment in
which the service is running.Table 2. Default version of the client-side human
service for each environment
Environment
Process Center server
Process server
Process Portal
355
Procedure
1. Open the Process Designer desktop editor.
2. Open a business process definition (BPD) that includes the variables you want to
configure and go to the Variables tab.
3. For each variable whose runtime values you want to search or to make viewable
in the IBM Process Portal task list, select the Visible in Process Portal check
box in the Business Data section. For complex variables, be sure to select the
check box for each parameter you want to make available.Note: Only processlevel variables can be made available as business data for searches, but not
variables defined, for example, inside human services.
4. In the Alias text box, type a name for the variable. This is the name to use when
performing searches in IBM Process Portal. This is also the name that is seen by
users in Process Portal when they are viewing the data related to tasks in their
task list. If you use camel case, a mix of upper and lower case letters to indicate
word boundaries, the label for the variable will be parsed into a multi-word string.
For example, if your search alias is customerName, the label for the variable in
Process Portal will be Customer Name. Note: The search alias must be unique to
the variable type throughout the process server on which the BPD runs. If a
variable is shared by multiple BPDs (for example, a parent process and its linked
processes) and you want the variable to be searchable in all of those processes,
you must define the same search alias for the variable in each of the BPDs where
it is used.
5. Save your changes.
356
Results
Now when IBM Business Process Manager runs instances of the BPDs that contain
the configured variables, you can search for process instances that include these
variables in IBM Process Portal. The variables that have been made available to
search are also viewable to business users viewing the associated task in their task
list. Note: If a BPD or subprocess contains a linked process or subprocess that has
been specified as "Loop Type: Multi Instance Loop" with "Run In Parallel," users
cannot search for tasks using business data declared in the BPD or subprocess
even if that data has been specified as "Visible in Process Portal".
What to do next
Your IBM Business Process Manager administrator can create saved searches to
provide IBM Process Portal users with customized views of their tasks.
Parent topic:Configuring a role-based business user interface
Parent topic:Business objects and variables
Related information:
Declaring variables for a BPD or a service in Process Designer
Creating and maintaining saved searches for Process Portal
357
Procedure
- If your process includes user tasks that involve a simple decision, such as to
approve or reject a request or to choose between a set of options, you can design
the task so that the business user can complete it in the Process Portal without
having to open the coach for the task. Instead, the user clicks a button or chooses
between the options with a single click.
- If your process must have a low latency, for example, to achieve a business
service level agreement, you can enable the optimization of execution for latency.
This optimization means that one path through the BPD is performed using a
single thread on a cluster member, other paths are scheduled to use the default
shared pool of threads.
- Sometimes multiple sequential tasks in a process are assigned to the same user.
In Process Designer, you can configure individual activities to launch automatically
if they are assigned to the same person as the previous task. In the Process
Portal, if the owner of the first task is the same as the owner of the second, the
second task will launch automatically when the first task is complete.
- Not all process activities run predictably in each execution of a process.
Sometimes a user must launch a new task that is outside of the normal process
flow. For example, they might need to cancel the process or they might need to
complete a separate but related business action, such as updating customer
contact information. Ad hoc processes are actions that you can expect users to do
at some point during at least some process instances. You can add ad hoc start
events and subsequent activities to your BPD, and the business user is able to
launch the ad hoc process from the Process Portal environment.
- Configuring activities for inline completion
Some activities in your process application can be completed with a single action,
such as an approval, rejection, or a simple decision. Using the services provided in
the system toolkit in Process Designer, you can configure these activities to be
performed by the business user in Process Portal with a single click action that
does not necessitate the user opening the coach interface.
- Optimizing BPD execution for latency
Select the optimization for latency to reduce thread context-switching for BPDs
that require low latency responses. When enabled, this optimization causes the
BPD to keep its execution thread rather than releasing it back to the pool of
358
359
Usage
Inputs
Use when the None.
task requires
the business
user to indicate
an approval or
rejection based
on the task
narrative and
the task details
that are
exposed in the
task list.
360
Outputs
approved Type:
Booleancommen
t Type: String
Simple
Completion
Simple Choice
None.
comment Type:
String
choices are
tw.resource.S
impleChoice.A
pprove,
tw.resource.S
impleChoice.R
eject
Procedure
1. Open the Process Designer desktop editor.
2. Open the business process definition (BPD) in the Designer view.
3. Select the task that you would like to configure for inline completion.
4. In the Implementation tab of the Properties view, select User Task as the task
type.
5. Select the predefined Human Service that corresponds with the type of inline task
that you are creating: Simple Approval,Simple Completion or Simple Choice
361
. Note: When the user is completing a Simple Approval task, they must enter a
comment if they select the reject option.
6. If you are creating a Simple Choice task, you can modify the choices presented to
the user, and provide additional choices. These options will each appear as a
button in the Process Portal task list.
A. Ensure that you have enabled The IBM BPM Advanced Features by going to
File > Preferences > IBM BPM > Capabilities. The check box for IBM BPM
Advanced Features should be selected.
B. In the Variables tab of the BPD, create a private variable to represent the
different options that are presented to the user. .
C. Because the variable will contain a list of strings, assign it type String and
select the Is List check box.
D. Under Default Value, select the Has Default check box.
E. The list of options, which appear as button labels in the Process Portal
interface, are added as string values for the autoObject[n] parameters.
When you first create your variable, the default appears as follows: var autoObject =
new tw.object.arrayOf.String();
autoObject[0] = "";
autoObject
362
363
Procedure
To enable the optimization for latency, complete the following actions.
1. Open the Process Designer desktop editor.
2. Open the BPD in the Designer view.
3. On the Overview tab, open the Advanced section.
4. Select Optimize Execution for Latency to reduce thread context-switching for
the BPD. Clearing the option turns off the optimization for the BPD.
Parent topic:Developing flexible and efficient process applications
Related information:
Maintaining and monitoring IBM Business Process Manager Event Manager
364
Procedure
1. Open the Process Designer desktop editor.
2. Open the BPD in the Designer view.
3. To configure an activity to automatically start the following task, go to the
Implementation tab of the first task in the sequence and select Automatically
flow to next task. In the Process Portal, if the owner of the first task is the same
as the owner of the second task, the second task starts automatically when the
first task is complete.
4. In the following task, set the assignment to be the last user: select Lane from the
Assign To list and select Last User from the User Distribution list in the
Assignments section of the properties for the activity.Activities are still considered
to be sequential even if they are separated by synchronous actions such as
exclusive gateways or tracking points. However, there are a number of scenarios
where the second activity in a sequence cannot be automatically started even if
the check box is selected on the first task:
- When the second task in the sequence is a system task.
- When an intermediate timer event or an intermediate message event follows the
first activity in the sequence.
- When the first activity flows to multiple tasks assigned to the same user, for
example in a multi-instance loop or a parallel (split) gateway.
- If the task is being tested in the Process Inspector.
- If the elapsed time between the end of the first task and the arrival of the token
at the next task is greater than the autoflow-timeout setting. By default, the
autoflow-timeout is set to 3 seconds. You can use the 100custom.xml file to
modify the value of the autoflow-timeout setting.
365
366
Procedure
To model a new activity or set of activities that a user can launch in the normal
process flow, complete the following steps:
1. Open the Process Designer desktop editor.
2. Open the BPD in the Designer view.
3. Add an ad hoc start event to your process diagram by dragging a start event from
the palette and specifying an implementation type of Adhoc in the Implementation
tab of the Properties view.
4. Add the activity or set of activities that occur when the start event is triggered. For
example, if you are designing a process application where business users can
look up a customer order history at any time in the normal processing of a
customer order, you might include a set of tasks for logging into the order history
database and submitting a query.
5. Connect the task or tasks to the new start event. When you deploy your process
application to the Process Portal, business users can launch the set of activities
from the action menu in the current application. New task instances are created
and appear in the task list for the user or team that is assigned to the new ad hoc
task.Important: Ad hoc task instances that were created during the running of a
process instance must be complete before the process instance completes.
6. Optional: Ad hoc actions might be associated only with a particular phase of the
process. For example, an order can be canceled before it has been sent out for
delivery, but after it has been delivered, the order can no longer be canceled. To
make an action available for only a certain phase of the process, complete the
367
following steps:
A. Add phases to your BPD to define the different phases in the running process.
For example, you might have a pre-delivery phase that contains all the
customer order activities that occur before the order ship, and a post-delivery
phase that contains the activities that occur after the order ships.
B. Move the ad hoc start event to the phase in which it should be available.
C. In the Event Visibility section, to restrict the visibility of the event by phase,
select phase.
In the Process Portal, the ad hoc action is in the action menu only while the
running process instance is in the specified phase.
7. Optional: Limit the type of users that run ad hoc actions in your process. For
example, you might want to limit a credit check override action to users who
belong to the managers team. To make an action available to only a certain team
of users, complete the following steps:
A. Add swimlanes to your BPD diagram and associate each swimlane with a
specific team. For example, you might have a swimlane for customer service
representatives and a swimlane for managers.
B. Move the ad hoc start event to the swimlane that is associated with the team
that should be able to launch the action in the Process Portal.
C. In the Event Visibility section, to restrict the visibility of the event by swimlane
select swimlane.
In the Process Portal, the ad hoc action is in the action menu only for users who
belong to the specified team.
Parent topic:Developing flexible and efficient process applications
Related information:
Creating a team
Deprecated: Enabling users to perform ad hoc actions
368
369
Procedure
1. Open the Process Designer desktop editor.
2. Open the process application in the Designer view.
3. Click the Servers tab, and then Add to add a new server.
4. In the Type field, select IBM Sametime Server.
5. Enter the information about your Sametime server.
6. Test the connection to the Sametime Connect server. Point your browser to the
following URL.https://sthost:secureport/stwebclient/popup.jsp
Where:
- sthost
Results
While working with business processes in Process Portal, users will be able to
search for and chat with other users within the context of tasks and process
activities.
Parent topic:Setting up collaboration features for business users
Related information:
Configuring Sametime Connect integration
370
Procedure
1. Open the Process Designer desktop editor.
2. Open the BPD in the Designer view.
3. To explicitly specify an expert group for an activity, select the activity and go to
the Assignments tab in the Properties view.
4. Specify the relevant team in the Experts Team field. If you have not already
created a team that defines the experts for this task, you can create a new team
to use.
What to do next
Your BPM administrator can configure the teams at run time to ensure that the
correct set of users are identified as experts for the activity in Process Portal.
Parent topic:Setting up collaboration features for business users
Related tasks:
Configuring runtime teams
Related information:
Creating a team
Getting help from experts to complete a task
371
Procedure
To enable the IBM Connections integration for Process Portal, complete the
following steps:
1. Open the Process Portal application in IBM Process Designer, click the Servers
tab, and then click Add to add the IBM Connections server.
2. In the Type field, select IBM Connections Server.
3. Complete the server locations information, including the host name.
4. Provide a user ID and password.Tip: If you want participants to use the IBM
Connections notification capability, which requires IBM Connections V4.0 or later,
the user ID and password to IBM Connections are required to enable the IBM
Connections server. On the administrative console for the IBM Connections
server, make sure that the user is a member of the trustedExternalApplication
security role in the WidgetContainer application. If your participants use only the
business card capabilities, specifying a user ID and password is not required.
5. Specify whether the IBM Connections server uses Secure Sockets Layer (SSL). If
Process Portal is accessed through HTTPS, select this setting. If Process Portal
is accessed through HTTP, do not select this setting.Tip: SSL is enabled by
default in IBM BPM, so unless your administrator disabled SSL, select Use SSL
372
Results
For IBM Process Server profiles, the Process Portal snapshot is installed on IBM
Process Server.
Process Portal users can see the business card information of the users whom they
work with.
What to do next
For all Process Portal users, make sure that the email addresses in their IBM
Business Process Manager user profiles match the email addresses in their IBM
Connections user profiles.
So that process participants receive notifications in IBM Connections, ask them to
update their user preferences as described in Setting preferences in Process Portal.
373
Procedure
1. Open the Process Designer desktop editor.
2. Open the BPD in the Designer view.
3. Grant users access to the Process Performance dashboard tab.Without access to
the tab, users cannot see the Process Performance dashboard in Process Portal.
To grant access, on the Overview tab for the process, assign a group to the
Expose Performance Metrics option.
4. Enable due dates and at-risk calculations.Due dates and at-risk calculations are
enabled for a process by default in the Advanced section on the Overview tab.
At run time, due dates are calculated from the creation time of the process
instance based on the value of the Due in field and the settings for the work
schedule. Due dates are used in Process Portal to determine whether a process
instance is on track for timely completion. At-risk calculations are based on the
average time it takes to complete an instance of the process.
A. Enable the due date. At-risk calculations require that the due date is enabled.
B. Set the expected duration of process instance in the Due in field. By default,
each instance is due 8 hours after it is started. If you select Days for the
duration, you can also add hours and minutes to the elapsed time, for example
2 days, 4 hours, and 30 minutes.
C. Optional: Enable at-risk calculations.
Due dates are shown for the instances of this process in Process Portal. Process
owners can modify the due dates in the Gantt chart. If at-risk calculations are also
enabled, instances become at risk when the average time to completion is longer
than the time left to the due date.
374
Results
The Process Performance dashboards for processes and instances in Process
Portal are enabled for process management.
Important: The following Process Portal action policies determine who is authorized
to view and change the projected path:
- ACTION_VIEW_PROCESS_DIAGRAM
- ACTION_VIEW_CRITICAL_PATH
- ACTION_CHANGE_CRITICAL_PATH
- ACTION_CHANGE_INSTANCE_DUEDATE
The action policies are contained in the BPMActionPolicy configuration object.
Administrators can modify the set of users who are assigned to these policies.
What to do next
375
Define the work schedule for the process and set the due date for individual
activities.
- Setting the work schedule for a BPD
The due date for a process instance is the expected date and time that all
activities related to a process instance should be completed. The due date is
affected by the work schedules of the users who receive the tasks involved in the
process.
- Specifying activity due dates
Activity due dates are used to calculate the expected completion time for an
activity. This completion time is used during process execution to establish which
tasks are overdue or at risk of being overdue.
Parent topic:Designing process interactions for business users
Related information:
Configuring access to Process Portal action policies
The Gantt chart
Setting up autotracking
Sending tracking definitions to Performance Data Warehouse
Creating a timing interval for a business process
376
Procedure
In the Work Schedule section on the Overview tab, specify the working hours that
users are available to complete work.
- The Time Schedule specifies the normal business hours that work can be
completed. For example, if you expect the users completing the task to be
available Monday through Friday, 9 AM to 5 PM, you can select this schedule from
the list.
- Timezone specifies the timezone that you want to apply to running instances of
the current BPD. All standard time zones are available.
- The Holiday Schedule is a list of dates that are exceptions to the normal time
schedule.
If you use the default values for any of these fields, the values are taken from
corresponding settings in the 99Local.xml file.
Tip: If you expect some activities to be completed by users with a specific work
schedule, you can specify a different work schedule for that activity in the Properties
view for that activity.
For all of the work schedule values, you can use a JavaScript expression with
predefined variables. You can enter either a String (or String-generated JavaScript)
or a JavaScript expression that returns a TWTimeSchedule or TWHolidaySchedule
variable. If you use a String, then IBM BPM looks up the schedule by name
according to those rules. If you use one of the TWSchedule variables, then IBM
BPM assumes that the schedule is filled in appropriately. To view the parameters of
the TWTimeSchedule or TWHolidaySchedule variables, open them from the System
Data toolkit.You can also write an IBM BPM service to dynamically set the overall
work schedule for a BPD and store the entire work schedule in the
TWWorkSchedule variable. The TWWorkSchedule variable includes parameters for
timeSchedule, timeZone, and holidaySchedule. To view the parameters of the
TWWorkSchedule variable, open it from the System Data toolkit.
377
- Examples
You can specify a task Due in value in days, hours, or minutes, with an optional
clock time.
- Managing time and holiday schedules
You can manage time and holiday schedules by using the JavaScript API. You
can set time and holiday schedules for activities on the Implementation tab. After
you add a new time or holiday schedule, it immediately becomes available in the
time or holiday schedule list in the authoring environment.
Parent topic:Enabling process instance management for a BPD
Related information:
Using JavaScript variables and objects inside Process Designer
The 99Local.xml and 100Custom.xml configuration files
378
Examples
You can specify a task Due in value in days, hours, or minutes, with an optional
clock time.
In these examples, assume that the assigned time schedule for our sample task is
Monday through Friday, 9 AM to 5 PM, which means that only 8 hours of work time
are available on each business day. Depending on the task Due in value
assignment, this time schedule assignment has the following impact when it comes
to the task due date calculation:
1. If you specify the task Due in value as 24 hours, the task is allowed to take 3
days (meaning 3 business days), because each business day contains only 8
hours of available work time.
2. If you specify the task Due in value as 7200mins or 120hours, this time is divided
by 8 hours per business day, based on the time schedule. The calculated task
due date therefore moves out into the future, because for every business day
available identified by the time schedule, only 8 hours per business day can be
worked on the task.
3. If you specify the task Due in value as 5 days (meaning 5 business days), this
means 5 business days as available according to the time schedule. In our
examples, all Saturdays and Sundays are excluded, which means that more than
5 days might pass before the task is due.
4. If a holiday schedule is assigned, and if the assigned time schedule allows the
days identified by the Holiday Schedule value to be excluded from the task due
date calculation, the task due date moves even further out into the future.
379
Procedure
1. Create an integration service by using a server script similar to the following
script:var holidaySchedule = new tw.object.TWHolidaySchedule();
holidaySchedule.name = "holidaySchedule" + new Date().getTime();
holidaySchedule.dates = new tw.object.arrayOf.Date();
holidaySchedule.dates[0] = new tw.object.Date();
holidaySchedule.dates[0].parse("20100101", "yyyyMMdd");
holidaySchedule.dates[1] = new tw.object.Date();
holidaySchedule.dates[1].parse("20100223", "yyyyMMdd");
holidaySchedule.dates[2] = new tw.object.Date();
holidaySchedule.dates[2].parse("20100308", "yyyyMMdd");
holidaySchedule.dates[3] = new tw.object.Date();
holidaySchedule.dates[3].parse("20100501", "yyyyMMdd");
holidaySchedule.dates[4] = new tw.object.Date();
holidaySchedule.dates[4].parse("20100824", "yyyyMMdd");
holidaySchedule.dates[5] = new tw.object.Date();
holidaySchedule.dates[5].parse("20091231", "yyyyMMdd");
tw.system.addHolidaySchedule(holidaySchedule).
2. Save and run the integration service.Note: It might take some time for the new
holiday schedule to be available in Process Designer after running the integration
service. To make use of your new holiday schedule right away, restart Process
Designer before you begin modeling.
3. Create a business process definition (BPD), and add an activity with a default
service.
4. Link the activity in a start-end flow.
5. On the Implementation tab of the activity, select the holiday schedule that you
created, and then set the time schedule to 7AM-7PM Every Day.
6. Save the BPD.
7. Run the BPD, and then open the Process Inspector tab to verify the due date
calculation.
Parent topic:Setting the work schedule for a BPD
380
Procedure
1. Select an activity in the diagram and go to the Implementation tab of the
Properties view.
2. In the Priority Settings section, specify the expected duration of the activity in
the Due In field. If you select Days for the duration, you can also add hours and
minutes to the elapsed time, for example 2 days, 4 hours, and 30 minutes.
3. In the other fields in the Priority Settings section, specify values for the
properties that affect the working hours that are available to complete work.You
can leave the Time Schedule, Timezone, and Holiday Schedule fields set to
the default value: (use default). If you use the default values, the time schedule,
time zone, and holiday schedule that are specified for the business process
definition (BPD) are used for the activity. For more information, see Setting the
work schedule for a BPD.
- The Time Schedule field specifies the normal business hours. For example, if
you expect the users who work on the task to be available Monday through
Friday, 9 AM to 5 PM, you can select this schedule from the list.
- In the Timezone field, select the time zone that you want to apply to the tasks
that result from the current activity. For example, if you expect the users who
work on the task to be in California, you can select the US/Pacific time zone
from the list.
- The Holiday Schedule field contains a list of dates that are exceptions to the
normal time schedule. If you use a JavaScript expression to define a holiday
schedule that is specific to users who work on this task, enter either a String (or
String-generated JavaScript) or JavaScript that returns a TWHolidaySchedule
variable. If you use a String, then IBM BPM looks up the holiday schedule by
name according to those rules. If you use a TWHolidaySchedule variable, then it
is assumed that the holiday schedule is inserted appropriately. To view the
381
What to do next
If you plan to enable projected path management for the BPD, keep in mind that
variable-based due dates used in the implementation of activities are not detected in
the projected path.
382
Procedure
1. Open the Process Designer desktop editor.
2. Open the BPD in the Designer view and go to the Overview tab.
3. In the Advanced section, change the text in the Instance name field if you want
the name of each instance to be something other than the BPD name. Be sure to
retain the quotation marks around the text. By default, the instance ID is
appended to the instance name that you specify, using the
tw.system.process.instanceId variable. You can remove this variable or use
the variable picker to choose additional variables.
4. Save your changes.
Parent topic:Designing process interactions for business users
383
384
385
activity in a BPD.
- Tracking groups of process variables
Use tracking groups if you want to explicitly control your tracked data and tracking
points. For example, you can group the variables that you want to track by type,
strategically place tracking points in your BPD, and track variables across multiple
BPDs. With tracking groups, your tracking points can also span multiple BPDs.
- Creating a timing interval for a business process
To enable process owners to analyze the amount of time that elapses between
certain steps in a business process, you can add tracking points to the business
process definition (BPD) and then create a timing interval to capture the duration
between the defined start and end points.
Parent topic:Enabling processes for tracking and reporting
Related information:
getBPMProperty command
setBPMProperty command
deleteBPMProperty command
386
388
389
390
KPIs
Key performance indicators (KPIs) are measurements that IBM BPM tracks at
process run time, storing results that you can use to analyze process and task
performance in the Optimizer. IBM BPM includes the following types of KPIs:
KPIs
Standard KPIs
Custom KPIs
Description
Located in the System Data Toolkit. By
default, most of the standard KPIs are
associated with each activity that you
add to a BPD diagram. Click the KPIs
option in the properties for an activity to
see the associated KPIs. Each of these
KPIs has default settings that you can
change.
You can define custom KPIs and
associate them with one or more
activities in your BPDs.
When you run instances of a business process definition (BPD), IBM BPM tracks
and stores data for configured KPIs in the Business Performance Data Warehouse.
IBM BPM uses stored KPI data when you run certain types of historical analyses in
the Optimizer. Not all historical analyses available in the Optimizer rely on data that
is generated and stored because of KPIs.
Note: The standard KPI, Total Time (Clock), is associated with each BPD by
default. To view the settings for this KPI, click the Process KPIs tab in the Designer.
You cannot alter the settings for this KPI.
SLAs
You can create service level agreements (SLAs) that are based on standard and
custom KPIs. With SLAs, you establish a condition for one or more activities that
triggers a consequence. For example, you can create an SLA that causes IBM BPM
to send an email notification when a particular activity takes longer than expected to
run.
When you run instances of your processes, SLA consequences do not trigger until
the associated activity starts or completes. For example, if you configure an SLA to
send an email notification when a particular activity takes longer than two days to
run, IBM BPM does not send the notification when the violation occurs. Instead,
IBM BPM sends the notification when the activity is complete. Therefore, if the
activity takes three days to complete, IBM BPM sends the notification then,
informing users of the violation. With SLAs you can report violations and, over time,
understand the trend in violations.
To enable Process Portal users to immediately react to time-based conditions for
391
one activity, use a timer event to capture the violation. If an SLA is not based on
time, consider using exposed process values (EPVs) to model the SLA. To provide
immediate notification of violations, develop the appropriate implementation for your
needs (such as a timer event for an escalation), and then create an SLA so that you
can track and report historical trends.
SLAs enable in-depth performance analysis over time, as described in the following
table:
Analysis
My SLA Overview dashboard
Description
View this report in Process Portal to see
the name, description, and status of each
configured SLA, and a trend chart of
violations for all SLAs or a specified SLA.
The My SLA Overview dashboard is not
exposed by default for Process Portal
users. If you want process participants to
see the My SLA Overview dashboard in
their tabs list, you must expose it
manually, as described in step 10 of
Creating SLAs in Process Designer.
Use SLA data that is stored in the
Business Performance Data Warehouse
to create custom reports using IBM BPM
or a third-party tool. You can use the
SLASTATUS and the
SLATHRESHOLDTRAVERSALS
database views to query the data..
When you are running scenarios, choose
the SLA visualization mode to display
results that are based on SLA violations.
392
Procedure
1. Open the Process Designer desktop editor.
2. Open a process application in the Designer view.
3. Click the plus sign next to Performance and select Key Performance Indicator
from the list.
4. In the New Key Performance Indicator window, type a descriptive name for the
new KPI and click Finish.
5. Provide a description for the KPI in the Documentation field.
6. In the Details section of the window, select the Unit for the KPI from the dropdown list. For example, if your company assembles cell phones and you want to
measure the number of phones in production, select Count from the drop-down
list.
7. To roll up the unit you are tracking into a higher-level KPI, click Select to choose
the KPI that you want. IBM Business Process Manager displays the KPIs in the
current process application and any KPIs in referenced toolkits, including the
System Data toolkit. For example, select the standard KPI, Resource Cost, to
roll the Count KPI from the previous step into a higher-level KPI. You can click
New to create a new KPI. Click the X icon to remove a roll-up KPI.
8. In the Roll-up multiplier field, specify the value by which to multiply the unit that
you are tracking before the data is collected in the roll-up KPI. For example, to
obtain an accurate Resource Cost for the previous step, enter the value of each
cell phone in the Roll-up multiplier field. Rolling up to higher-level KPIs is useful
when you create SLAs. The Resource Cost example in this procedure shows how
to create an SLA for a condition where the cost of resources in production was
either too high or too low.
9. Click Save.
Parent topic:Autotracking IBM Business Process Manager performance data
393
Procedure
1. Open the Process Designer desktop editor.
2. Open the BPD in the Designer view.
3. Select the activity that you want to associate with a KPI and go to the KPIs tab in
the Properties view.
4. To add a KPI, click Add and select the KPI or KPIs that you want. IBM Business
Process Manager displays the KPIs in the current process application and any
KPIs in referenced toolkits, including the System Data toolkit.
5. In the Assignment Settings panel, clear the Use KPI defaults check box if you do
not want to use the default assignments for the selected KPI.
A. Select the assignment type from the drop-down list. The assignment type
establishes how the value for the KPI is determined.
B. For KPIs that measure time, the assignment type is Automatic and cannot be
changed. Automatic assignment means that IBM BPM automatically tracks and
stores the values for these KPIs.
C. For other KPIs, you can choose from the following assignment types:
Assignment type
Value per Hour (clock)
Description
Enables you to multiply the specified
value times the total number of hours
spent on the activity.
Enables you to multiply the specified
value times the number of working
hours spent on the activity.
Enables you to specify a value for the
KPI.
Enables you to supply custom scripts
to track the value for this KPI.
Enables you to specify the number of
times an activity must be performed
before it is considered rework.
6. In the Threshold Settings area, clear the Use KPI defaults check box if you do
not want to use the default threshold settings for the chosen KPI. If you do not
use the default thresholds, you can indicate the type of performance that you
394
395
Creating SLAs
Create service level agreements (SLAs) so that you can analyze the performance of
your business processes over time.
Procedure
1. Open the Process Designer desktop editor.
2. Open a appropriate process application or toolkit in the Designer view.
3. Click the plus sign next to Decisions and select Service Level Agreement from
the list.
4. In the New Service Level Agreement window, type a descriptive name for the
new SLA and click Finish.
5. Describe the SLA in the Documentation field.
6. In the Trigger section of the window, the default trigger statement is displayed:
Whenever the condition is violated. Complete the following steps:
A. Click Whenever (displayed in blue font and underlined) to change the trigger
for the SLA. For example, if you select Violated % of the time over period,
the trigger statement changes to When the condition was violated 10%
of the time over the last day.
B. Click 10% of the time and set the percentage.
C. Click last day and set the time frame.
7. In the Condition section of the window, the default condition statement is
displayed: TheTotal Time (Clock) KPI for <select activities> is greater than 1
day. Complete the following steps:
A. Click Single value and choose Single value, Sum of values over time, or
Average value over time.
B. Click Total Time (Clock) and choose the key performance indicator (KPI)
that you want to use.
C. Click <select activities> and choose the activities that you want to apply this
SLA to. All activities are displayed under the BPD that they are in.
396
D. Click Greater than and choose greater than, less than, or equal to.
E. Click 1 day and choose Threshold, % above threshold, % below threshold
, Value above threshold, Value below threshold, or Value. Then, set more
parameters as necessary.
8. In the Consequence section of the window, select the check box next to the
action that you want to take when the specified condition is violated.
A. To choose the Send email option, click <enter email address> and provide
the address or addresses of the recipients of the notification. Separate
addresses with a comma.
B. To choose the Initiate process option, click <select process> and select a
BPD. IBM Business Process Manager displays the BPDs in the current
process application and any BPDs that are referred to in toolkits. The process
that you run as a consequence of the violation must have the following input
variables:
Input variable
violationRecord
Type
SLAViolationRecord
parameters
XMLElement
Description
Indicates which SLA was
violated, to what degree,
and when
Reserved for future use
9. Click Select next to the Expose to view label and select the team whose
members can view data for this SLA in the My SLA Overview dashboard in
Process Portal.
10. Click the Save icon in the toolbar.
11. Expose the My SLA Overview dashboard so that it is available in Process Portal:
A. In Process Designer, open the Process Portal application.
B. Click Performance and then open PM SLA Overview.
C. In the Exposing section, click Select next to the Exposed to field to choose
the team whose members can view and use the My SLA Overview
dashboard. To create a team, click New. To remove an assigned team, click
the X icon next to the Exposed to field.
D. Save your changes.
12. Test the SLA in the My SLA Overview dashboard in Process Portal. If the
dashboard does not display any data, complete one of the following steps:
- In the Process Portal application, select Implementation > Periodic SLA
Update, and click Run now.
- Include the Update All SLA Statuses service from the system toolkit in a
process application, and run the process application in Process Portal before
you test your SLA.
Parent topic:Autotracking IBM Business Process Manager performance data
397
Setting up autotracking
You need to set up autotracking before you can use the ad hoc wizard. When
autotracking is enabled for a business process definition (BPD), data for any nested
processes of that BPD will also be tracked. Subprocesses and services inherit the
setting of the parent process.
Procedure
1. Open the Process Designer desktop editor.
2. Open the BPD in the Designer view.
3. Click the Tracking tab for the BPD.
4. Ensure Enable Autotracking is selected.
5. In the Autotracking Name field, enter the name you want to use.
6. In order to analyze process data according to particular business variable values,
set the variables as follows.
A. Click the Variables tab for the diagram.
B. For each variable you want to track, right click it and then click Track this
Variable.
7. Save your changes.
8. Click File > Update tracking definitions to send the new tracking requirements
to the Business Performance Data Warehouse.
Results
When you run instances of the process, IBM Business Process Manager stores the
tracked data for each variable in the appropriate column. Each row in a Tracking
Group view represents a discrete unit of tracked data.
Parent topic:Autotracking IBM Business Process Manager performance data
398
399
Procedure
1. Open the Process Designer desktop editor.
2. Open a process application in the Designer view.
3. Click the plus sign next to the Performance category in the library, and then
click Tracking Group from the list of components.
4. In the New Tracking Group window, enter a name for the tracking group.
5. Click Finish. The Tracking Group window opens in Process Designer.
6. For each process variable you want to track, add a field to the tracking group.
A. Click Add in the Tracked Fields panel to add the field. The new field is added
with the default name UntitledNumber (string).
B. In the Tracked Field Details panel, specify the name and type for the process
variable. You can also include documentation.
C. When prompted, save the changes.
Attention: A tracking group can have a maximum of 50 fields for each of the
data types String, Number, and Date/Time.
7. Open the business process definition and add one or more tracking events to
the diagram.
8. For each tracking event, select it and open the Implementation tab.
9. Add the process variables that you want to associate with each tracked field.
10. Save the business process definition.
11. To send the new tracking information to the Business Performance Data
Warehouse, click File > Update Tracking Definitions .
What to do next
Associate process variables with each tracked field in the tracking group.
400
Procedure
1. Open the Process Designer desktop editor.
2. Open the business process definition (BPD) in the Designer view.
3. Add a tracking event to your BPD.
4. Select the tracking event and open the Implementation tab.
5. Click Select and select the tracking group you want to use.
6. Select the check box of each tracked field you want to use and click the selection
icon ( ) to bind a process variable to it.
7. Save your changes.
8. Click File > Update Tracking Definitions to send the new tracking information to
the Business Performance Data Warehouse.
Results
By updating tracking definitions, you automatically created a view in the Business
Performance Data Warehouse database. This new view displays the values of each
variable associated to the tracking group.
Parent topic:Tracking groups of process variables
401
Procedure
1. Open the Process Designer desktop editor.
2. Open a process application that contains a BPD.
3. In the Designer library, expand Performance by clicking the plus icon, and then
click Timing Interval from the list of components.
4. Type the timing interval name in the Name field, for example,
TimeToCompleteRequest, and then click Finish. The Timing Interval window
opens in Process Designer.
5. Define the timing interval.
A. To add the start and end points for the timing interval, select the Add button in
the Start Points and End Points panels.
B. To indicate the binding calculation you want to use for the start and end points
in the interval, select the Calculation Bound list in the Start Points and End
Points panels.
C. Save your changes.
Results
Timing intervals are available in the Overview page of the Process Performance
dashboard in Process Portal.
Parent topic:Tracking IBM Business Process Manager performance data
Related information:
Deprecated: Defining reports in Process Designer
402
403
Description
404
Results
When you send tracking definitions, either directly or as part of a snapshot
deployment, the Performance Data Warehouse establishes the structure in its
database to hold the data that is generated by the Process Server when you run
instances of your processes. In IBM BPM, these tracking requirements are called
definitions because they establish the database schema in the Performance Data
Warehouse to accommodate the tracked data generated by the Process Server.
405
Procedure
If you want to expose a performance scoreboard to your Process Portal users,
complete the following steps:
1. Open the Process Designer desktop editor.
2. Open the process application.
3. Click Performance and then open the scoreboard.
4. In the Exposing section, click Select next to the Exposed to field to choose the
team whose members can view and use the scoreboard. To create a team, click
New. To remove an assigned team, click the X icon next to the Exposed to field.
5. Save your changes. The scoreboard is available in the Process Portal Organize
tabs list for the members of the team that it is exposed to.
Parent topic:Enabling processes for tracking and reporting
406
Procedure
1. Open the Process Designer desktop editor.
2. Open the process application.
3. Click File > Ad Hoc Report Analysis.
4. Define the content of the report. Select the variables for the X and Y axes from
the corresponding bindings lists. You can also specify a time period filter and a
business data filter.
5. Click the Refresh icon to preview the chart.
6. When you are satisfied with the appearance of the chart and the data, click the
Create Report from Chart button.
7. In the Create Report window, give the report a name, and click Finish.
8. Create the scoreboard to display the report.
A. In the library for the BPD, expand Performance, and select ScoreBoard from
the list of components.
B. In the New Scoreboard window, give the dashboard a name, select a layout,
and click Finish.
9. Assign the report to the dashboard.
A. In the Scoreboard window in the Reports section, click Add, and then the
report.
B. In the Layout section, select the Enabled check box, and type a title in the
ScoreBoard title field. This title is what Process Portal users see in the list of
dashboards.
C. In the Exposing section, click Select next to the Exposed to field, and select
the team whose members can view this dashboard in Process Portal.
Results
When you log in to Process Portal as a member of a team to whom the dashboard is
exposed, you can see the new dashboard in the list of dashboards. Click the
dashboard to display the report.
407
What to do next
After installing a process application snapshot that includes the dashboard, you can
adjust the members of the team to whom the dashboard is exposed.
408
Procedure
To create a custom chart type:
1. Open the Process Designer desktop editor.
2. Open the process application.
3. Click the plus sign next to the All category in the library and select Chart Type
from the list of components.
4. In the New Chart Type window, enter a name for the chart type and click the
Finish button.
5. Optionally provide information about the new chart type in the Documentation
text box.
6. In the Chart Definition text box, enter the Cascading Style Sheet (CSS) definition
for your custom chart type. By default, the Chart Definition text box includes the
CSS framework for a new definition to help you get started. You can use the
framework to build a definition for the new chart type or you can overwrite the
framework by copying and pasting an entire CSS definition from another
application like IBM ILOG JViews Charts.
7. Click Preview to ensure that the CSS definition produces the chart layout that you
expect. If not, refine the definition until it meets your needs.
8. Click Save in the main Process Designer toolbar to save the custom layout.
Parent topic:Defining reports in Process Designer (deprecated)
409
Building cases
A case is a project that starts and finishes over time to resolve a problem. The
problem can involve a claim or a request or a proposal and be supplemented by
many documents and records relevant to the case. A case usually involves multiple
people from inside and outside of an organization. These people often have a
relationship to each other. For example, a customer with a problem and a
corporate support representative who solves the problem for the customer.
Case management functions are only available if you have IBM BPM Advanced with
the Basic Case Management feature installed.
To create a case, you identify the user activities that are needed to complete the
case and then group those activities into a case. You identify the documents that
are used and the teams of users that work on the activities. You also identify the
conditions that are required to start and complete the case and activities. Finally,
you create the user interface that case workers see in Process Portal.
The following diagram illustrates the main tasks and activities that are associated
with building a case.
a case management application that is based on closely related cases and then
deploy that solution into a production environment. Case workers can then
complete work items that are associated with cases.
Designing a case
To design a case management application, identify what user activities are
needed to accomplish the main user goal. Decide what business level activities
and steps you need, and then group those activities and steps into a case. As you
identify the content that is needed to complete the activities, decide who works on
the content. Then, consider what does or does not need to happen to complete
an activity.
Opening Case Designer from Process Center
You can configure process applications and toolkits so that users can open them
in
Case Designer from Process Center.
Creating a case type
A case type defines the activities that are needed to resolve a specific business
problem. A case type also defines who works on these activities and the steps they
take to resolve the problem. At run time, a business user works with a case,
which is an instance of a case type. A case type also uses document types that
define the documents that are required for the case.
Adding a case activity
An activity in a case is a discrete task that can be completed by a person or a
system as part of that case. Typically a case has a number of activities. You add
an activity in a case type and classify it as either is required or optional, and also
define the order in which activities are performed by setting preconditions, and
add implementation logic.
Creating a document type
Document types classify the documents that belong to a case. Document types
provide order to the many kinds of documents that can occur in a case. You can
configure a case to start when a document of a specified document type is filed
into the IBM BPM content store. You can also set a precondition on an activity to
start the activity when a document of a specified document type is filed in the IBM
BPM content store
Creating case user interfaces
Create user interfaces that a user sees for the case instance in Process Portal.
Testing and debugging a case type
Play back your case type in the Inspector to test and debug your activities.
Services to support case management applications
You can create services to use with your case management applications. These
services, which can do standard tasks in your case management applications,
can be shared by
all case types in a process application.
The IBM BPM content store
The IBM BPM content store is a CMIS-enabled embedded document repository
that is used to store IBM BPM documents in IBM Business Process Manager
Advanced version 8.5.5.0 or later. It supplants the document attachment feature
that was used in earlier releases. The IBM BPM content store supports all Content
Management Interoperability Services (CMIS) operations and most inbound events
and you can use either Coaches or Heritage Coaches to work with IBM BPM
documents in the content store.
411
412
413
414
- Process application
- A process application contains one or more related case types that
provide the documents, data, business processing, and routing to the case
workers.
For example, a process application for a human resources
department might include
a case type for new hires. The process
application might also include a case type
for retirement and a case
type for employee termination.
- Case types
- Case types define the activities and might use document types to
support the activity. Case types also specify the teams that must complete the
activities to solve a business problem. The case type also includes
properties
that are shown to case workers in Process Portal. Case
types make up a
case management application. A case is an
instance of a case type.
- Document types
- Document types help you to organize and classify the documents that
belong to a case. You can provide more information about the documents by
assigning properties to the document type. For example, a document
type might be a
job application form.
- Preconditions
- A case type can contain preconditions. A precondition
determines
the action to take if particular conditions are met in a case. You can
use preconditions to determine process routing.
415
- Coaches
- You can define a launch user interface or an instance user interface for a
business user to work with your case. The implementation of these user
interfaces
by a client-side human service can contain coaches.
Human services with coaches
can also be used to implement
activities.
- Activities
- A case contains activities. An activity in a case is a discrete task
that
can be completed by a person or a system as part of that case. You can
implement an activity as a user task, which is a client-side human service, a
subprocess, or a linked process. For example, an activity might be to
review new
hire applications. A case is not complete until all
activities that are marked as
required during design are completed.
Also, all activities that are started must
be completed. For
details about the states that an activity can be in, see Runtime states for
activities in process applications.
- Linked process
- A case can call a reusable process, which is known as a linked process. Since
a
linked process is reusable, it can be used by many cases. For
example, creating a
customer account might follow a common set of
steps; so, if created with a linked
process, it might be used by many
cases.
- Subprocess
- A subprocess is an option for encapsulating logically related steps within a
case. Steps in a subprocess can directly access variables from the case.
No data
mapping is required. However, unlike a linked process, a
subprocess can be
accessed and instantiated only from the case
that is using it. It is not reusable
by any other case.
- Client-side human services
- Human services are the human actions in a process that must be
completed for an activity. For example, a human service might be to review a
job
application form. There are two types of human services in IBM
BPM; heritage
human services, and client-side human services.
Case
activities use client-side human services. Use the Client-side
human service
editor to create and edit human services.
- Teams
- A team represents a specific business function. For example, a team
might be an Applicant or Supervisor. You assign users and groups to teams.
You can
assign them at design time with the Designer or at run time
with the Process Admin
Console. Teams are associated with cases.
You can also specify which users can
start a case.
Parent topic:
Related concepts:
Scenario: Financial services credit card dispute resolution
Scenario: Automobile insurance claims
416
Related information:
Business process management and case management
Client-side human services
417
Problem
Banks that issue credit cards are seeing a significant increase in dispute cases. In
addition, regulatory reform and an increased focus on customer satisfaction put
more pressure on banks to handle each case as efficiently as possible. The
banks require a solution that enables them to process each incoming dispute and
decide whether to forward it to the credit card company for chargeback.
Credit card companies have strict requirements for how cases can be submitted.
The bank solution must provide accurate and appropriate information to the credit
card company to ensure efficient processing.
Solution to problem
A business analyst at the bank, Anna, studies the requirements of the credit card
company's dispute process. Anna determines the types of information that the
credit card company requires to process a dispute. Anna uses the IBM Business
Process Manager tools to quickly design and create an application. The
application helps the bank representatives capture all of the required information
in a case and attach extra records and documents to the case. Anna determines
what teams must be involved in processing dispute and fraud cases, and Anna
assigns permissions to different groups based on those teams.
Scenario
Jane, a credit card customer of the bank, buys a table from an online merchant for
$400. The table is not delivered within three weeks as the merchant promised.
Jane sends email and calls the merchant. However, no one responds. Because
Jane used a credit card for the transaction, Jane calls the bank for help.
Jane enters the account information by using the automated phone system. As a
result, the call is routed to Nicole, a senior customer service representative. When
Jane explains the situation, Nicole opens a case to track the dispute. Nicole finds
the purchase transaction for the table from Jane's account and adds the record to
the new case. Nicole forwards the call and the case to a dispute agent, Frank.
During the conversation with Jane, Frank enters data into the case by using a form
that captures details about the transaction, the merchant, and the customer. Jane
says that a copy of the receipt can be provided and a copy of the delivery
agreement. Frank creates an activity in the case to follow up on requesting the
documents. Frank tells Jane that an investigation is proceeding, and adds Jane's
preferred contact method to the case. When the call ends, a recording of the call
418
Parent topic:
Related concepts:
Case management concepts
419
Problem
Automobile insurance claims can involve input and supporting documentation from
many sources. The sources include the claim submitter, the repair shop, the
police, and other official sources of information about vehicle value or road
conditions. In addition, different analysts are often required to evaluate and add
information to an insurance claim during processing. All documentation and claim
information must be available and easily accessible to enable adjustors to
properly evaluate and resolve the claim.
Individual claims can vary greatly. This variability can require case workers to start
discretionary processes and to involve new teams. The variability can also change
how and when tasks are completed as the claim is routed through the
organization.
Solution to problem
Javier, a business analyst at the automobile insurance company, is working on
making the automobile claims process more consistent. Javier uses IBM
Business Process Manager to design an application with activities that involve
multiple human services. Javier creates teams for each step in the claims process.
Javier assigns permission to the teams for the groups of employees who do the
activities at each stage in the process.
The application that Javier designs combines these elements.
- Claim properties, such as policy number and accident details
- Teams, such as claims adjustor or fraud investigator
- Case types, such as general claims, claims with injury, or major loss claims.
In addition, IBM Business Process Manager enables Javier to create a flexible
solution. Javier can quickly change teams, processing, or add activities when they
are needed.
Scenario
Carly is driving on a roadway when Carly's car strikes a large object. Although Carly
is not hurt, the car is too damaged to drive. The police arrive, and a tow truck is
dispatched. When Carly calls the insurance company, customer service
representative Chris opens a case for the claim. Chris uses a First Notice of Loss
(FNOL) form to record the information. When Chris enters Carly's home phone
420
number, many of the form fields are automatically populated with data that is
retrieved from the system.
Chris asks about Carly's location, and tells Carly to have the tow truck driver take
the damaged car to a specific nearby repair shop. The case information is
forwarded to the car repair shop. Chris tells Carly how to use a PDF form that is
available on the insurance company's website to provide details about the
accident. Chris gives Carly the case number that was generated when Chris
opened Carly's case. Carly is told to include the case number on the form.
Chris recalls a memorandum about recent fraudulent claims that involve collisions
with roadway debris. Chris creates a discretionary task to involve a fraud
investigator in the claim.
Later, Carly downloads the PDF form from the insurance company's website and
enters the accident details and the case number. Carly mails the form back to the
insurance company. Because this action is set as a precondition on Chris's task
to review the claim, Chris is notified when the form is added to the case. Also, on
the company website, Carly uses the case number to access a tool for uploading
photographs of the damaged car.
John, the agent at the car repair shop, receives notification about the case. John
creates a task to provide an estimate for repairs. John makes sure that the $4500
estimate for repair does not exceed the value of the car and submits the estimate
to the insurance company. John uses Carly's contact information to notify Carly
that the estimate was submitted.
The case is routed to Lisa, an adjustor. Lisa reviews the case and the supporting
documents, including the police report and the photographs of the damage. The
estimate is below the threshold for investigation, and the fraud investigator set the
flag for possible fraud to false. Lisa approves the claim.
After the case is closed, the insurance company receives a report from the police.
The report says that a freight company was charged with dropping the object that
caused Carly's accident. Lisa reopens Carly's case. Lisa contacts Javier, who
adds a team to the system called recovery expert. The recovery expert creates
new tasks to attempt to reclaim the cost of the repairs from the freight company.
Because of the flexibility of this case management system, case workers can
resolve problems more quickly and efficiently, and customers can close their
claims more easily.
Parent topic:
Related concepts:
Case management concepts
Scenario: Financial services credit card dispute resolution
421
Designing a case
To design a case management application, identify what user activities are needed
to accomplish the main user goal. Decide what business level activities and steps
you need, and then group those activities and steps into a case. As you identify the
content that is needed to complete the activities, decide who works on the content.
Then, consider what does or does not need to happen to complete an activity.
Case management functions are only available if you have IBM BPM Advanced with
the Basic Case Management feature installed.
One approach to designing an application is to first identify the types of documents
that people in your organization must complete for some activity. For example, to
resolve a credit card dispute claim, you might need a dispute form and a customer
to complete the form. Then, a service representative must review that form. Next,
you might initiate a fraud investigation if the circumstances warrant such an
activity. In that case, you might need a fraud investigator to review the claim.
Therefore, for a credit card dispute case, the application must include these
artifacts:
- Dispute form
- Fraud investigation form
Your application must also include these teams:
- Customer
- Customer service representative
- Fraud investigator
You can use the Case Type editor to help you think through the various document
types, teams, case types, and activities that you need.
Parent topic:
Building cases
Related concepts:
Case management overview
Related tasks:
Creating a process application for your case types
Creating a case type
Creating a document type
Related reference:
Services to support case management applications
422
Center
You can configure process applications and toolkits so that users can open them in
Case Designer from Process Center.
Procedure
- To configure a new process application so that users can open it in Case Designer
from Process Center:
1. Log in to Process Center.
2. Select the Process Apps tab.
3. Click Create New Process App.
4. In the Create New Process App window, enter a name and
an
acronym for your process application.
5. Select the Allow users to open the process application in the
web-based Case Designer check box.
- To configure an existing process application so that users can open it in Case
Designer from Process Center:
1. Open the process application in Process Designer.
2. Click Manage.
3. Select the Allow users to open the process application in the
web-based Case Designer check box.
- To configure a new toolkit so that users can open it in Case Designer from Process
Center:
1. Log in to Process Center.
2. Select the Toolkits tab.
3. Click Create New Toolkit.
4. In the Create New Toolkit window, enter a name and an
acronym
for your toolkit.
5. Select the Allow users to open the toolkit in the web-based Case
Designer check box.
- To configure an existing toolkit so that users can open it in Case Designer from
Process Center:
1. Open the toolkit in Process Designer.
2. Click Manage.
3. Select the Allow users to open the toolkit in the web-based Case
Designer check box.
Parent topic:
Building cases
423
424
Procedure
1. Select Cases from the library. Click +. In
the Cases menu, select Case Type
.
2. In the New Case Type dialog, enter a name for the case type.For example, if
you were creating a case type for the Credit Card Dispute Resolution
application, you might enter Manage Dispute.
3. Click Finish. The Case Type editor opens for your case type in the
Overview
page. The case type that you created is added to the
Case Type menu that
is listed when you click
Cases.
4. Optional: In the overview page, use the Documentation field to add information
about the case type that you want to share with your development team.
5. Configure how the case is started in Process Portal. See Configuring how a
case is started.
6. Assign teams whose members can start a case, or instance owner teams whose
members can work
with the case in Process Portal. See Assigning teams to a
case type.
7. Create variables for the information that you want to share across activities.
Create
properties that are stored in case folders. Adding a case type variable
or property.
8. Add activities that define the business tasks that make up the case. Add
preconditions and
behavior that determine how and when the activity starts.
Implement the activity. Adding a case activity.
9. Creating user interfaces for the case Creating case user interfaces.
10. Adding folders that are used to group the documents in Process Portal and in
the IBM BPM
content store Adding case type folders.
What to do next
425
426
Procedure
To configure how a case is started:
1. Open the case type that you want to configure.
2. Optional: Specify the type of document that can automatically start a case:
A. In the Starting Document section of the Overview page, click
Select to
choose a document type or New to
create a document type.
B. Optional: To automatically initialize case folder property values with the
values of matching document properties, select the Map document
properties check box. If you select this check box, the properties on a starting
document are matched to the
properties on the case folder. Properties are
matched based on the symbolic name, which is
composed of the business
object name, type, and cardinality. For example, assume that you have a
business object that is called
customerId of simple type string. Both the
case type and the starting
document type contain a property of type
customerId. When a starting
document is created, these properties are
matched and the value of the case's customerId
property is updated with
the value of the starting document's customerId property.The identifier of the
starting document is available as a JavaScript system variable:
tw.system.currentProcessInstance.startingDocumentId. You can use
this identifier in case activities, such as with Enterprise Content Management
operations. The case type is started by the default snapshot of a process
application. In Process Center, the tip is the default snapshot unless another
snapshot was explicitly configured to be the default. If the case type is defined
in a toolkit, it is started only if a snapshot of that toolkit is referenced by a
process application. If multiple process applications reference the same toolkit
that contains a case type with a starting document, multiple case instances are
started.
3. Specify the team that can manually start a case by clicking Select
or New for
the Expose to Start option. You must select a team to work with the case in
Process Portal.
Parent topic:
Related tasks:
427
428
Procedure
1. To add a variable, select the Variables tab and click
+ beside Input, Output,
or Private.
2. Beneath Details add an appropriate name and, if you want, a
description in
the Documentation field. By default, the variable has a
String type. To change
the type, click Select and select another type
from the menu. To make a
variable a list, that is, make the variable an array, select
List. Select Visible
in Process Portal to make a
variable visible and available for searching in
Process Portal. If you select Visible in
Process Portal, a name in the Alias
field is required. This
name appears in the following places:
- The Data section of the View Instance page
- The Details section when you work on a task
- The expanded task.
3. To use an existing business object as a type, click Select and
retrieve the
business object from the menu. To create a new business object, click
New
and follow the steps in Creating custom business objects in Process Designer.
For example, in the Manage Dispute case type, you might require a business
object to
contain personal information about the owner of the credit card. You
can add a
CreditCardOwnerPersonal business object with these parameters.
- cardNumber (Integer)
- expiryDate (Date)
- givenName (String)
- surname (String)
4. Select + beside Case Folder Properties to
create a variable that is a property
of the case folder.In addition to the attributes for an input, output or private
variable, case folder
properties have display and symbolic names. The
Display name field
shows a generated name that is based on the property
type. This name appears on the case
folder in the IBM BPM content store. If
you create
a case folder property that is called customerCardNumber and
customerCardNumber is based on a
simple type that is called
CustCardNumber, then the Display name field
becomes Cust Card Number.
429
In other words, the simple type name becomes the display name with a
slight
change for readability.
The Symbolic name field shows a generated name that is based on the
property type. You can use this name for Enterprise Content Management
operations.
A property that is a list must contain values when used. Null values result in an
error.
5. The Visible Variables section shows the names and aliases of
variables or
properties that are identified as Visible in Process
Portal. If you want, you
can remove that visibility.
6. Save your work when finished creating your variables.
Parent topic:
Related information:
Creating custom business objects in Process Designer
Data mapping in Enterprise Content Management operations
430
Procedure
1. To add a folder, open the case type.
2. Click the Folders tab. You can create a folder directly under the root case folder,
or under a previously created
folder.
3. Click + beside the folder under which you want to create your
folder. Add a
name for your folder and save your work. You can create as many folders and
subfolders as you want. For example, in the
Manage Dispute case type,
you might want to have several folders for the parties involved.
You might
create folders for information on the credit card owner, the vendor, and
third-party corporations that are involved with the transaction. You might create
this
folder structure.
- Credit Card Dispute Documents
- Credit Card Owner Documents
- Historical Documents on Owner
- Monthly Transactions
- Vendor Documents
- Historical Documents on Vendor
- Monthly Transactions
- Third-party Services Documents
- Delivery Records
- Shipping Records
What to do next
The case folder and its subfolders are accessible through the Document Explorer
coach view in the Instance Details UI that is provided with the Dashboards toolkit.
See Default Instance Details template.
If you are working with the IBM BPM content store on an Enterprise Content
431
Manager server, you can modify your Launch UI so that a user can view
documents in the case folder that you specified in the Folders page. See
Creating case user interfaces.
You can also access the folder structure programmatically by using Enterprise
Content Management operations. The identifier of the root case folder is available
within a case as
tw.system.currentProcessInstance.caseFolderId. When
you create a subfolder programmatically by using the Enterprise Content
Management operation Create Folder, you must use IBM_BPM_CaseSubFolder
as the Object type ID.
Parent topic:
432
Procedure
1. Open the case type for which you want to assign teams.
2. Click the Overview page.
To assign the team of users that can start a case instance in Process Portal.
1. Select a team for the Expose to start option. You can also create a
new team
here. See Creating a team.
To assign the team of users that can work on the case in Process Portal.
1. Select a team for the Instance owners option. You can also create a
new
team here. See Creating a team.
2. Save your work.
Parent topic:
Related tasks:
Configuring how a case is started
433
Procedure
1. Open the case type for which you want to add an activity and switch to the
Activities page.
2. Decide whether the activity is required or optional and create the activity in the
appropriate section.
Option
Description
434
Required
Manually
Description
The activity starts automatically
when a case is created or when
the
preconditions are
met for the activity.
The activity must be started by
a user. You can define
preconditions that
must be met to put a manual
activity into Ready state.
However, the activity does
not start until the case worker
decides to manually start the
activity.
435
436
Procedure
To set a precondition:
1. Open the case type.
2. In the case type editor, switch to Activities, and select the activity that you want.
3. Switch to the Preconditions page.
4. In the Precondition Event section, select the event that triggers
the
precondition expression to be evaluated.
Precondition event
No precondition event for
this activity
Description
Automatic activities start as
soon as the case is launched.
Manual activities must be
started by a user.
437
tw.system.currentAdHocActivityInstance.enablin
gDocumentID
You can
use this identifier
to further process the document
within the activity by using
Enterprise
Content
Management operations.
A case property or variable is You can select multiple case
updated
properties or variables from the
list provided. The
activity
starts when any of the specified
properties or variables are
updated.
A precondition expression is There is no precondition event
met
to be triggered. You must
specify a precondition
expression, and when the
expression is met, the activity
starts.
5. Create an expression if your precondition requires it. The expression must
evaluate to true
at the time the precondition event occurs, for the activity to
start.
A. Click the + icon in the Precondition Expression section heading.
B. Specify the parameters of the expression. For example, you might specify
claimAmount is greater than 100. You
can specify multiple
expressions for the precondition. For example, you might specify
creditCardNumber is not equal to 0 and vendorName is not like
Unknown.
C. Select Match All if both expressions must evaluate to true for the
activity
to start. Select Match Any if the activity can start when any
one
expression evaluates to true.
Parent topic:
439
Procedure
1. Open the case type, and select the activity that you want to implement.
2. Switch to the Implementation tab and select the activity
type, and
then select the implementation. You can choose from one of the
following implementations.
- User task
- A task that is performed by a user in Process Portal. The user task
is implemented as a client-side human service, which creates the
user interface.
- Linked process
- Calls another process within the process application.
- Subprocess
- A non-reusable process.
3. Add the details of the implementation that you selected:
- Client-Side Human ServiceYou can select an existing client-side human
service, or create a new
one. When you create a new clientside human service, the input and
output variables are
automatically taken from the case type variables.
All input and
output variables are selected by default. You can clear
the
input and output variables that you do not want to use with your
human service.
Under Priority Settings,
specify your settings. A priority that
ranges from lowest to highest
establishes the priority you want
for this activity in the Process
Portal. Specify a due in time;
that is, when the activity must be
completed from the time the
activity begins, and the timezone that is
used by the due in
field.
Under Task
Header, specify a display name for the activity in
the
Subject field. If you do not specify a
display name, the activity name is used. In the
Narrative
field, you can enter a description
or instructions for this activity.
You can use JavaScript to specify
these fields.
In the Process Designer web editor, create your
client-side
human service as described in Building a client-side human service.
- SubprocessDouble-click the activity and the
subprocess
editor opens. Create your subprocess as described in Modeling non-reusable
subprocesses.Warning: If you define a
repeatable activity
440
Related tasks:
Adding a case activity
Related information:
Subprocess types
Client-side human services
Building a client-side human service
Creating a team
441
Procedure
1. Select Cases from the library. Click +. In the Cases menu, select Document
Type.
2. In the New Document Type dialog, enter a name for the document type.For
example, if you were creating a document type for the Credit Card Dispute
Resolution application, you might enter SupportingCustomerDocumentation.
3. Click Finish. The Document Type editor opens for your document type.
4. Enter the properties for the document type. The properties provide the structure
for your document type. These properties become fields at run time when a
business user enters information in them. You can use the following attributes:
- List: the property is a list (or array).
- Hidden: the business user cannot see the property in Process Portal, but it is
visible in the IBM BPM content store.
- Required: the property must be completed by the business user. The property is
marked as required in Process Portal, and the user cannot proceed without
entering a value for it.
Restriction: A document property can reference only a custom simple type
business object. It cannot reference a complex type business object or one of the
simple types, such as a String, directly. Also, it cannot reference a custom
simple type business object that has a base type of Selection.
For example, SupportingCustomerDocumentation might have a property for the
customer's credit card number with a required attribute. If all vendors were
available in a list, another property might be the name of the vendor that sold the
goods to the customer with a list attribute. Finally, there might be a property for a
system where the document is stored with a hidden attribute.
5. Document properties also have display and symbolic names. The Display name
field shows a generated name that is based on the property type. This name
appears in Process Portal and on the case folder in the IBM BPM content store.
The Symbolic name field shows a generated name that is based on the property
type. The symbolic name is a unique identifier for the property within the IBM
BPM content store. You can use this name for Content Management
Interoperability Services (CMIS).
442
What to do next
To rename or delete a document type, select it in the Document Type list and either
right-click or click the arrow to its right.
As time progresses, you might update the properties of your document type. If you
remove properties from your document type, the removed properties still appear in
Process Portal. The removed properties remain active until they are deleted from
the embedded content store by using the cleanupDocumentStoreProperties
command.
443
Parent topic:
444
Procedure
To create a case instance user interface, first create a client-side human
service, which includes a generated coach. You can then create your customized
interface by
modifying the generated service and coach.
1. Open the case type for which you want to create the user interface.
2. Switch to the Views page.
3. Select the interface that you want to create, for example
Default under
Details UI.
4. Click New beside Client-side human
service and enter a name for your
user interface. In the New
Client-side Human Service page, if you click
Next, you
see a list of case variables that you can add to your human
service. Select the variables
to be added to the interface of the human
service.You do not need to map the variables between the case type and the
human service. The
case type variables are already mapped to the human
service variables with the same
name.
5. The client-side human services editor opens. Switch to the
Variables
page. Notice that the input and output variables that are mapped from the case
type are
locked. You can edit these variables only in the case type editor.
445
What to do next
If your variables change in the future, you can use the Sync button
to
synchronize the variables and human service. During synchronization, you can
optionally
choose to regenerate the human service body. Regenerating
replaces any customization that
was done in the human service.
Parent topic:
Building cases
Related information:
Client-side human services
447
Case type
To test and debug a case type, you must play back the case type in the Process
Designer desktop editor.
1. Open the process application that contains the case type in the Process Designer
desktop
editor.
2. In the library, click Cases and select the case type that you want to
test.
3. Right-click the case type and click Playback > Run Process
4. At the Switch View prompt, click Yes. The
Inspector opens showing the case
type as a BPD.
5. Click Executing Phase to view the activities.
6. Click and activity to select it and click Run or
Debug to launch the Inspector.
7. To view the user task activities (client-side human services) in Process Portal,
click
Run the details UI for the selected BPD instance.
Subprocess activities
To test and debug an activity that implements a subprocess, you must play back
the case type in the Process Designer desktop editor.
1. Open the process application that contains the case type in the Process Designer
desktop
editor.
2. In the library, click Cases and select the case type that you want to
test.
3. Right-click the case type and click Playback > Run Process
4. At the Switch View prompt, click Yes. The
Inspector opens showing the case
type as a BPD.
5. Click Executing Phase to view the activities.
6. Click the subprocess activity and click Run or
Debug to launch the Inspector.
Parent topic:
Building cases
448
449
450
Parent topic:
Building cases
Related concepts:
Case management overview
Designing a case application
Related tasks:
Creating a process application for your case types
451
452
Building cases
453
store
454
455
artifacts
You can update case artifacts and then playback or redeploy a process application.
For example, you can update a process application and then playback or
redeploy the process application again. The redeployed process application
contains case types and document types previously deployed. Modifying a case
type or a document type and then redeploying the process application affects
existing case and document data and new case and document data.
Case management functions are only available if you have IBM BPM Advanced with
the Basic Case Management feature installed.
The result of changes in the IBM BPM content store is discussed. These changes
are
relevant only when you are working with the IBM BPM content store
through the Enterprise Content
Management integration tools.
The following table describes the effects of updating case artifacts and then playing
back
or redeploying a modified process application. Table 1. Affects of process
application changes
Type of changes
Result
New item, such as a No issues.
new document type
or a new case type.
Delete an item, such No issues.
as a document type
or a case type.
Add a property
definition to a
document type or
case type.
Delete a property
definition from a
document or case
type.
Comments
456
Change the
cardinality of a
document type or
case type property
definition.
No issues.
457
The validation
settings for a simple
type business object
that is used in a
case type or
document type
property
458
In the case of
documents, the
existing values are
validated against the
new
setting of the
validation value only
when there is an
update to the
property.
New instances are
validated against the
new validation setting
value.
Changing the
validation setting
values can cause a
document to have
invalid
values.
Required property
Some existing items
setting for document are affected. See the
type properties.
Results column for
the validation
settings for a simple
type business object
used in a case type
or document type
property.
Existing instances
require a value for
the property only if
the instance is
updated. New
instances require a
value for the
property.
Before you can check
out an existing
document that
contains a
required property, the
property must be set
with a valid value.
Hidden property
Existing items are
All existing instances
setting for document affected. See the
of the property and
type properties.
Results column for
new instances use
the validation settings the updated
for a simple type
setting. If the property
business object used was changed from
in a case type or
hidden to visible, then
document type
all existing
property.
instances and new
instances display the
property. If the
property was
changed
from visible to
hidden, then all
existing instances
and new instances do
not
display the property.
Document type name New and existing
New and existing
and description.
items are affected.
instances of the
document class in the
IBM BPM content
store use the new
display
name and
description.
Case folder structure New cases are
New instances of the
for a case type.
affected.
case use the updated
folder structure.
Parent topic:
Related information:
459
cleanupDocumentStoreProperties command
460
Creating a team
A team is a group of users that perform similar tasks, and consists of a set of
members and a team of managers. Teams are used to manage the tasks that users
can perform in Process Portal. Because any team can be added as the manager of
another team, you can flexibly define your organization's management structure.
To add the members to a team, you can directly add users or groups from the user
registry, or you can use a team retrieval service to define a team dynamically at run
time. You can use teams in a number of ways in Process Designer:
- Assign a team to an activity or a lane in a business process. The users in that team
can work with the tasks that are created for the activities in Process Portal.
- Specify a team of instance owners for a case type, so that users in that team can
work with case instances of that type in Process Portal.
- Provide a team with the authority to view performance data and the performance
dashboard in Process Portal.
- Set simulation properties for a team to define the performance expectations for the
team, and run simulation on the business process activity.
Procedure
To create a team and add members, follow these steps:
1. In the library, click the plus sign to next to the Teams category.
2. In the New Team window, enter a name for the team and click Finish.
3. Select the team members in one of the following ways:
- Select users or groups that are defined in the user registry.
- Use a service to dynamically retrieve a team at run time. You can create a new
service, or you can select a service that you have already created. See Setting
up a team retrieval service.Note: To select a service to dynamically retrieve a
team at run time, you must start the Process Designer desktop editor.
Tip: To prevent problems occurring when there is a large number of users in the
system, IBM BPM ignores the tw_allusers user group for task reassignment.
For task reassignments, add individual users or other groups instead of using
tw_allusers.
4. Select the team of managers that can manage the team's tasks in the Team
Performance dashboard.
5. If you want to simulate a process, set the simulation properties for the teams that
are assigned to the swimlanes in the process model. These settings represent the
performance expectations for the team. For more information, see Setting
simulation properties for teams
A. Open the Process Designer desktop editor.
B. Open the team, and enter the simulation properties.
6. Click Save in the main toolbar. Your team is added to the list of teams, which is
shown when you click Teams.
- Using services to define dynamic teams
You can use the team retrieval service and the team filter service to dynamically
461
determine who is eligible to perform activities. These services can take parameters
from environment variables to influence the team selection.
- Setting up a team retrieval service
You can define a service that dynamically returns a set of users and managers at
run time.
- Setting up a team filter service
You can use a team filter service to dynamically prevent certain users from being
assigned to an activity. The filtering can be based on any criteria and can use input
parameters from relevant process variables to determine which users to filter out.
- Defining team managers
To define who the managers of a team are, you must select a team of managers.
In this way, with teams managed by teams, you can define the management
structure of your organization.
- Defining Team rules (deprecated)
When you choose to establish team members by using an expression, you can
define rules to determine those members.
Parent topic:Building process applications
Related information:
Setting up a team retrieval service
462
463
464
Procedure
1. Open the Process Designer desktop editor.
2. If you want to create a team that is dynamically resolved, complete the following
actions in the Designer view.
A. In the library, click the plus sign to next to the Teams category.
B. In the New Team window, enter a name for the team and click Finish.
3. In the team editor, choose to specify team members by using a service.
A. Click New.
B. Enter a suitable name for the service, for example, Claims Team Retrieval
Service.
C. Select the Variables tab. The mandatory input and output variables are
already present and are locked. If the new team retrieval service requires
information from the activity, add input parameters and specify the variable
details. Important: If you want to use this dynamic team as the managers of
another team, you can use only additional input parameters that have default
values that are defined for them.
D. Select the Diagram tab and provide the implementation of the service. Based
on the input parameters, the service must return a Team object that contains a
list of team members. It can also optionally include the name of a team of
managers, and optionally the name of the team (this parameter is ignored).
E. If you want the results of the service to be cached for each combination of
input parameter values, select the Overview tab, then in the Service Result
Cache section, select Enable caching of service results to display the cache
configuration fields. By default caching is disabled.
- When caching is disabled, the Cache results for section is not displayed.
- When caching is enabled, the Cache results for section is displayed. By
default, when caching is enabled, the results for each combination of input
parameter values are kept in the cache for 12 hours. To change the caching
period, use the Days, Hours, Minutes, and Seconds fields to select the
duration that you want. Important: Depending on the size of the results, you
might need to tune the size of the service results cache to avoid memory
problems. By default, the cache stores up to 4096 results. You can change
the size of the cache by setting a different value for <service-result-
465
Restriction: The service results cache setting works only for top-level
services, which are services that are directly started by a BPD. When a
service is called by another service, the service results cache setting for the
nested service is ignored and the results for the nested service are not
cached.
4. To use an existing team retrieval service, complete the following steps.
A. Click Select. A selection dialog is displayed that lists all existing services that
match the team retrieval service template.
B. Select the team retrieval service that you want to use.
5. If the team retrieval service that you selected requires extra parameters, then the
Team Retrieval Service Input Mapping section is displayed. For each required
parameter, enter the corresponding environment variable name or literal, for
example tw.env.businessPriority.
Results
The team's members are determined dynamically by the appropriate team retrieval
service. If you defined a new team retrieval service, it is available to select when you
assign activities to teams, as described in Assigning teams to BPD activities.
Parent topic:Creating a team
Related information:
Creating a team
Setting up a team filter service
Using services to define dynamic teams
466
Procedure
1. Open the Process Designer desktop editor.
2. Click the plus sign in the All category, and create an Integration Service.
3. Enter a suitable name for the service, for example, High Value Claims Team
Filter Service or Separation of duties - filter out previous user.
4. Select the Team Filter Service template and click Finish.
5. Select the Variables tab. The mandatory input and output variables are already
present and are locked. If the new team filter service requires information from the
activity, click Add Input to specify more input parameters. In the Details section,
specify the name of the variable, its type, and any default value. Tip: The input
variables that are required depend on the policy that the filter must implement. If,
for example, certain users cannot work on tasks that are above a certain value,
the service might need the process variable tw.local.estimatedClaimAmount
as an input parameter that the service implementation uses to determine which
users to eliminate from the input team. Similarly, for example, to implement a
separation of duties policy, where the user who completed the previous activity
cannot be assigned to the following one, you might specify an input variable
previousUser that you map to the process variable tw.system.user.id so that
the service implementation can remove the previous user from the input team.
6. Select the Diagram tab and provide the implementation of the service. Based on
the input parameters, the service must return a Team object that contains a list of
team members. It can also optionally include the name of a team of managers,
and optionally the name of the team (this parameter is ignored).
7. If you want the results of the service to be cached for each combination of input
variables, select the Overview tab, then in the Service Result Cache section,
select Enable caching of service results to display the cache configuration
467
Results
The new team filter service is added to the list of team filter services that you can
select when you assign a team to an activity.
What to do next
Apply the new team filter service to the team that is assigned to an activity by
completing Assigning teams to BPD activities.
Parent topic:Creating a team
Related information:
Setting up a team retrieval service
Using services to define dynamic teams
468
Procedure
For statically defined teams, complete the following actions.
1. If you want to define a new team of managers, complete the actions in Creating a
team.
2. If you want to add or remove managers from an existing team of managers,
complete the following actions using Process Designer.
A. Open the team of managers that you want to modify.
B. Add or remove users and groups in the members list.
C. Optional: To modify the team that manages this team of managers, use the
Managers section. You can either create a team, select an existing team, or
delete the currently selected team of managers.
Parent topic:Creating a team
469
Procedure
To define rules, follow these steps.
1. Open the Process Designer desktop editor.
2. Open the team that you want to edit.
3. Click Add Rule to choose the type of rule you want.When you define team rules,
you have the following types from which to choose:
Table 1. Rule types available for defining teams
Rule type
Participant Rule
User Attribute Rule
Expression Rule
Description
Enables user selection according to
team membership.
Enables user selection that is based on
user attributes.
Enables the selection of users who
match a particular expression that you
provide.
4. Supply the necessary information for the type of rule that you choose.
- For a Participant Rule, supply the input that you want for the following
specification:
Who belong to team select participant.
Table 2. Input required for a Participant Rule
Expression
belong
select participant
Action
Click belong to choose either belong
or do not belong.
Click select participant to choose an
existing team.
- For a User Attribute Rule, supply the input that you want for the following
specification.
Who have an attribute select user attributeequal toenter value.
Table 3. Input required for a User Attribute Rule
470
Expression
select user attribute
equal to
enter value
Action
Click select user attribute to select an
existing user attribute definition.
Click equal to to choose from: equal
to, not equal to, less than, less than
or equal to, greater than, or greater
than or equal to.
Click enter value to display a field in
which you can enter either an IBM
Business Process Manager variable or
a JavaScript expression that produces
the value that you want to compare. Be
sure to surround any strings in the
expression with double quotation
marks.
For example, when you select Using Expression and define a User Attribute
Rule, you can enter an expression that returns a default value when the complex
variable is null and the attribute for the variable otherwise. For example, if the
user attribute is a string, the expression can be:tw.local.processData==null ?
"":tw.local.processData.targetView.complexity
Note: Users that do not have a value set for the selected user attribute definition
are ignored for any of the operators.
- For an Expression Rule, supply the input that you want for the following
specification:
Who match expression enter value.
Action
Click match to choose either match or
do not match.
Click enter value to display a field in
which you can enter either an IBM
BPM variable or a JavaScript
expression that produces the value that
you want to compare. Be sure to
surround any strings in the expression
with double quotation marks. The
expression must evaluate to a specific
user name.
471
472
473
process instances, you need to configure each variable in the Process Designer to
be available to search. In addition, the business data about a task that business
users see in their task list needs to made available to search in order to be
viewable in the task list.
Parent topic:Building process applications
474
Selection
Boolean
Description
Allows alpha-numeric characters to be
entered into the variable.
Accepts digits without a decimal place,
such as 45 or 20.
Accepts digits with up to two decimal
places, such as 45.3 or 20.13.
Allows date and time formats to be
entered into the variable.
Allows date formats to be entered into
the variable as times. The user enters a
time, and before the variable is entered
into the symbol table, it is converted to
and behaves like a date.
Allows you to provide a list of possible
entries to a user, of which the user can
select only one. A selection is a list of
different values; each value is typed as a
string. A selection variable appears at
run time on a Coach form as a dropdown list or as radio buttons.
Accepts either true or false as values.
It appears at run time on a Coach form
as a check box.
475
Structure
476
Description
Top-level Process Designer namespace
Access Process Designer JavaScript
objects and business objects (variable
types)
Access and update BPD and servicelevel variables
Access system features and functionality
Access security functionality
Access exposed process values (EPVs)
Access environment variables
477
Procedure
1. In Process Designer, open your process application.
2. In the library, beside Data click + and select Business Object to create a new
business object. Alternately, you can create a business object by clicking New
when you create a variable. The New Business Object window opens.
3. In the Name field, type a name for the custom business object and click Finish.
Remember: Names of business objects are case-sensitive.
4. Under Behavior, you see definition types.
- Simple type
- Creates a new simple business object that is derived from one of String,
Integer, Decimal, Date, Time, or Selection. A simple type that is created with
the business object editor cannot be initialized before use with a business
process or service unlike a complex type. If you do initialize a simple type
that uses the new keyword, then you receive a runtime error.
- Complex type
- Creates a new complex business object by specifying the parameters for the
structure. Complex structure types that contain primitive types must initialize
the primitive types before use.
An example of initializing a primitive type before use is
tw.local.myListOfComplexTypes[0].name = "";.
5. Select a type from the Definition type list.
- If you selected Simple type, select the type of your business object and specify
a validation if you want. For example, you might want to limit the number of
characters for a String type.Case runtime behavior affects some string
478
479
- A shared business object uses database resources. The data within a shared
object is persisted to the database when:
- The shared object is created
- The task is persisted to the database
- The JavaScript method save() is performed on the shared business object.
- Each shared object is logically connected to the business process instance that
created it. When the business process instance is deleted (for example, when you
delete a business process instance that was running in the Inspector), the shared
object data in the database is also deleted.
- If you clear the Shared Object check box at a later point in time, the business
object will no longer be accessible to other instances at run time.
- If the shared business object is created within a human service that can be started
and that activity is not bound to a business process instance, the shared business
object is connected to the activity's task instance. In such cases, the shared
business object is deleted if the task instance is deleted.
- If a shared business object is deleted from the database, the behavior of the tasks
or processes that reference the shared business object is undefined.
- Best practice for shared business objects: If you want to create shared business
objects that have a long lifetime, you may want to design a business process that
acts as a factory (that is, it is based on a factory method pattern). The result is your
shared business objects will remain in the database until the factory business
process is deleted.
- An output shared business object for an external service, such as a web service,
and an Advanced Integration Service will return a new and typically updated copy
of the original input shared business object. Therefore, your application should not
reference the input shared business object expecting an updated value if your
application is working with an external service or an Advanced Integration Service.
It should reference the new output shared business object.
- Shared business objects allow concurrent modification. For example, two users
can view and modify the same shared business object instance in a human
service. When users trigger a boundary event, the data of the shared business
480
object instance is saved. Only the fields that each user modifies are saved.
Therefore, if the two users modify different fields, both changes are saved. If both
users modify the same field, the last users update is saved. In addition to multiple
users, you can have a situation with automated steps, for example, a server script
that makes modifications to shared business objects.
You can create and retrieve the shared business objects you have created by using
a key, as shown in the following example. In this case, tw.object.SharedObject is
the shared business object.
// Create shared object
var sharedObject = new tw.object.SharedObject();
sharedObject.taskId = "init";
sharedObject.save();
481
482
3. In the Refactor window, the pane shows the business processes and services
that reference the business object. Select the business processes and services
that you want updated and click OK. If there are no references, the pane is blank;
however, continue to click OK to rename the attribute. You can copy the names of
the business processes and services to a clipboard if you want to analyze the list
later by clicking Copy To Clipboard.
4. Afterward, check all artifacts that you expected to be updated, particularly in
JavaScript sections. The refactor function updates attributes on objects in the
following situations:
- The object is assigned to a fully qualified business object that is instantiated with
the keyword new or to any ancestral attribute of the object. An example of an
ancestral attribute that would be refactored is
GreatGrandparentBusObj.GrandparentBusObj.ParentBusObj.busobj.name.
- The object is assigned to a local variable that does not have an ANY type or to
any ancestral attribute of the object.
In the first example, name would be updated. In the next two examples, id would
be updated.
var businessobject = new tw.object.BusinessObject();
businessobject.name = "John";
tw.local.customerInfo.id = 1234;
var customer = tw.local.customerInfo;
customer.id = 5678;
If you refactor a business object and one of its references is being edited by another
user, the reference is not selected to be refactored. A message specifies the user
who is editing the reference.
When you start the refactor window, the business object that is being refactored is
locked, as are any references that are selected to be refactored. When the refactor
operation is finished, the business object and the references are unlocked.
Limitations:
- JavaScript code in Coaches is not updated.
- To be listed as selectable for refactoring, the business processes or services must
reference the business object with the variables or variable fields that are found in
the Variables tab.
- Property names are not updated when the square bracket notation is used; for
example, in the following code, firstname, would not be updated:
customer['firstname'] = "John".
- Refactoring does not update the binding when the business object parameter
name is changed.
Renaming a variable
Variables are found within a business process or a service. In other words,
renaming a variable does not affect another business process or service. Renaming
a variable can affect a reference to it within the same business process or service.
To rename a variable, follow these steps:
483
1. Click the Variables tab and select the variable that you want to rename.
2. When you change the name in the Name field, a message says that to refactor
the value press Alt + Shift + R. Pressing this combination starts the Rename
window. Change the variable name in the New Name field. By default, when you
click OK, all references to the variable are updated. However, you have the option
of clearing Update references. In that case, none of the references to the
variable are updated. Unlike renaming a business object or attribute, you do not
see a subsequent panel where you select references or are shown no references.
484
485
Anonymous type
Schemas can be built with sets of named types, for example, an InvoiceType. Then
elements can be declared such as invoiceCanadian that reference those types.
However, if you only need to reference a type once then there is considerable
coding overhead. An anonymous type is used for these cases of a single reference.
To specify the value for an anonymous type, select Anonymous Type and select
true or false. The default value is false. Anonymous types can cause difficulties as
discussed in Web services hints and tips: avoid anonymous types. If you have read
the XSD generation pattern for business objects topic you will also know that the
true value is not honoured by the generator. Save your work. Click View XML
Schema. Your output should be similar to the following sample.
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:tns="http://EH" targetNamespace=http://EH"
elementFormDefault="qualified" attributeFormDefault="unqualified">
<xs:element name="employee">
<xs:complexType>
<xs:sequence>
<xs:element name="employeeNumber" nillable="false" type="xs:string" minOccurs="0" maxOccurs="1" />
<xs:element name="firstName" nillable="false" type="xs:string" minOccurs="0" maxOccurs="1" />
<xs:element name="lastName" nillable="false" type="xs:string" minOccurs="0" maxOccurs="1" />
</xs:sequence>
</xs:complexType>
</xs:element>
</xs:schema>
Element name
If the anonymous type property is set to true, this property places the anonymous
type under an element with the specified name.
Use the default value unless it is strictly necessary to make a change.
Element namespace
This property sets the namespace of the container element.
Use the default value unless it is strictly necessary to make a change.
486
<xs:element name="employee">
<xs:complexType>
<xs:sequence>
<xs:element name="firstName" nillable="false" type="xs:string" minOccurs="0" maxOccurs="1" />
<xs:element name="lastName" nillable="false" type="xs:string" minOccurs="0" maxOccurs="1" />
</xs:sequence>
</xs:complexType>
</xs:element>
</xs:schema>
Maximum occurrences
This property sets the maximum number of times that the parameter occurs. The
default value is 1. This property corresponds to maxOccurs in the XML schema.
Use the default value unless it is strictly necessary to make a change.
Minimum occurrences
This property sets the minimum number of times that the parameter occurs. The
default value is 0. This property corresponds to minOccurs in the XML schema.
Use the default value unless it is strictly necessary to make a change.
Name
This property overrides the name of the serialized parameter with the name that you
specify. The default value is the name of the parameter. This property corresponds
to the name attribute in the XML schema.
Use the default value unless it is strictly necessary to make a change.
Namespace
If you set the namespace for the business object, this property changes the target
namespace. The target namespace defines explicitly the elements that belong to
this instance of the namespace. You might want to change the target namespace if
you imported a WSDL file and the target namespace for your business object was
changed on importation. If you set the property for a parameter, it overrides the
serialized element namespace for that parameter.
To rename the target namespace, select Namespace and enter the target
namespace you prefer. For example: http://www.mycorporation.com/employees
. Save your work. Click View XML Schema. Your output should be similar to the
487
following sample.
<xs:schema targetNamespace="http://www.mycorporation.com/employees"
elementFormDefault="qualified" attributeFormDefault="unqualified">
<xs:complexType name="employee">
<xs:sequence>
<xs:element name="employeeNumber" type="xs:int" minOccurs="0"
maxOccurs="1" nillable="false" />
<xs:element name="firstName" type="xs:string" minOccurs="0"
maxOccurs="1" nillable="false" />
<xs:element name="lastName" type="xs:string" minOccurs="0"
maxOccurs="1" nillable="false" />
</xs:sequence>
</xs:complexType>
<xs:element name="employee" type="tns:employee" />
</xs:schema>
Nillable
This property determines whether the parameter can have a null value.
Use the default value unless it is strictly necessary to make a change.
Node Type
Nodes in an XML document can be defined as elements or attributes. A discussion
of these types can be read in Principles of XML design: When to use elements
versus attributes. In most cases, an element type is used which is the default, so
you do not need to set it explicitly. However, you can set it to use an attribute.
To change the type to an attribute, select Node Type and select Attribute. Save
your work. Click View XML Schema. Your output should be similar to the following
sample.
<xs:schema targetNamespace="http://EH" elementFormDefault="qualified"
attributeFormDefault="unqualified">
<xs:complexType name="employee">
<xs:sequence>
<xs:element name="firstName" type="xs:string" minOccurs="0"
maxOccurs="1" nillable="false" />
<xs:element name="lastName" type="xs:string" minOccurs="0"
maxOccurs="1" nillable="false" />
</xs:sequence>
<xs:attribute name="employeeNumber" type="xs:int" />
</xs:complexType>
<xs:element name="employee" type="tns:employee" />
</xs:schema>
Order
Order explicitly sets the order of the complex type's elements. Usually you would
leave the order in the XML representation of the business object exactly as it is in
the business object editor. However, you might want to change the order if the
488
Time zone
This property sets the time zone to use when serializing a date parameter. The
property is not used in WSDL generation or schema creation but it is used to display
date and time values. The default value is CLIENT. The other valid values are
SERVER and UTC.
Use the default value unless it is strictly necessary to make a change.
Type name
This property sets the qualified name of the type for the business object or
parameter.
Use the default value unless it is strictly necessary to make a change.
Type namespace
This property overrides the type namespace of the serialized XSD type with the
namespace that you specify.
Use the default value unless it is strictly necessary to make a change.
Wrap list
This property determines whether to create an array wrapper type to contain a list.
The default value is false, which means that the list is not wrapped. A list is an array
and it is specified when List is selected as an attribute. You might use this field if
you wanted to encapsulate the array. A wrapper type can be anonymous and the
name of the list items can be overridden. If you have not selected List for a variable,
489
this field and other fields with list in their name are disabled.
490
491
they are contained in. They can also have their own variables that are only relevant
within the context of the subprocess or event subprocess and any subprocesses or
event subprocesses they might contain.
- Testing declared variables and data mapping with coaches
When you declare and map variables in your BPD, you can test the mapping
between activities by using coaches and running your BPD in the Inspector.
Parent topic:Business objects and variables
492
To
Service
Type
Simple
Pass by
Value
Service
Complex
BPD activity
BPD activity
Linked BPD
Linked BPD
Simple
Complex
Service
Service
Nested service
Nested service
Simple
Complex
493
- So even though the BPD and two services reference separate objects, the
values of these objects are updated by the data store. This allows the running
services to operate on current data. See Creating custom business objects in
Process Designer for information on shared objects.
BPDs and services have references to their variables. When complex variables are
passed from a BPD to a service, a deep copy of the variable is transferred from the
BPD space to the service space, and the service gets a reference to the copy.
Similarly, when a complex variable is passed from the service to a BPD, a deep
copy of the variable is transferred from the service space to the BPD space, and the
BPD gets a reference to the copy.
When the service changes the values of the existing complex variable, the changed
values are passed back to the BPD by replacing the entire complex variable with a
deep copy from the service. If the replaced variable was originally passed by value
from an outer BPD, the inner and outer BPDs no longer access the same variable.
Therefore, changes made to the inner BPD are not reflected in the outer BPD.
- Example
- An outer BPD has a reference, tw.local.pair, that points to a NameValuePair
object, NVP1. The outer BPD passes its .pair reference to an inner BPD: Outer BPD > NVP1
Inner BPD -> NVP1
- The service exits and outputs the .pair, mapped back to the variable of the inner
BPD .pair. A copy of NVP2 is created, NVP3, and a reference is passed back to
the inner BPD.Outer BPD -> NVP1
Inner BPD -> NVP3
Recommended guidelines
Because of how Process Designer handles variables, follow these guidelines:
- If the variable is a simple type, declare the variable as an input and an output in
linked BPDs, services, and nested services.
- If the variable is a complex type, declare the variable as an input. Also, although
the output declaration is not required because complex types are passed by
reference, declare the variable as an output so that other developers will know that
the linked BPD, service, or nested service returns a complex variable.
- Always use an identical name and data type for a set of input and output variables
for data that is passed in, processed, and then passed back.
495
Description
Local variables that are used only within
the process.
Variable that represents input data
passed to the current BPD or service.
Variable that represents output data that
the current BPD or service returns to its
caller.
Special type of variables that you can
create to set or alter values while
instances of a process are running.
Only BPD variables that are marked as process instance identifiers can be
used for instance-based correlation of intermediate message events that use the
SCA triggering mechanism. A process instance identifier variable can be a private,
input, or output variable, and can be a simple or complex variable type.
Procedure
If you want to add an exposed process variable, click Link EPV, and then select the
EPV from the list. If you want to add a private, input, or output variable, complete the
following steps:
1. Open your BPD or service diagram in Process Designer.
2. In the Variables tab, click Add Private, Add Input, or Add Output to create the
corresponding variable.
3. In the Details section:
A. Type a variable name in the Name field.Note: Variable names start with a
lowercase letter, with subsequent words capitalized, for example: myVar. Do
not use underscores or spaces in variable names. Variable names are casesensitive.
B. Click Select next to the Variable Type field to select the type of the variable.
Custom business objects that you created are also listed.
C. Optional: Type a description of the variable in the Documentation field.
D. Optional: If you want your variable to be an array, select Is List.
496
4. Optional: To set a default value for the variable, in the Default Value section,
select Has Default, and enter the value in the corresponding field.
5. Optional: To include the BPD variable in the business data that users can view in
Process Portal, in the Business Data section, select Visible in Process Portal,
and type an alias in the Alias field.Tip: The search alias must be unique to the
variable type throughout the process server on which the BPD runs. If a variable
is used in parent and nested processes, use the same search alias if you want
search results to include all related processes.
6. Optional: To include the BPD variable values in the data that is collected and
used to create reports, in the Performance Tracking section, select Track this
Field.
7. To declare a BPD variable as a secondary process identifier, you must mark it as
a process instance identifier. In the Process Identification section, select
Variable is used as Process Instance Identifier. While it is possible to mark
any variable as process instance identifier, it is advisable to use a variable for this
purpose that is not too complex.Important: The value that is written to the
variable must be unique for each instance of the BPD. Because variables that are
selected as process instance identifiers can be written to only once, be careful
during initialization, data mapping, pre-assignments, and post-assignments to
avoid it ever being written to twice for an instance. Writing any value to such a
variable more than once causes an error.
Tip: If you clear the selection for a variable that is already used for correlation, the
variable is marked with an error icon on the Data Mapping tab.
Variables that are marked as process instance identifiers can be selected to be
used for correlation, and are indicated in variable selection dialogs by the text
[Identifier].
8. To save the configuration, click Save in the main toolbar.
What to do next
The BPD or service includes variables that can be passed to activities or services,
by mapping input and output variables. If you have a coach in the diagram, the
variables are directly available inside the diagram, and can be dragged in the layout
window.
Parent topic:Declaring and passing variables
Related information:
Using Service Component Architecture to interact with processes
Data tracking considerations
Mapping input and output data for an activity or step
Creating exposed process values (EPVs)
497
Procedure
1. Open the diagram of your BPD or service.
2. Click the activity in the BPD diagram or the step in the service diagram, and then
click the Data Mapping tab in the properties. The Data Mapping tab displays the
variables that are available from the service implemented in the activity or step.
- For receive events that are triggered using an undercover agent (UCA), both
identifier and non-identifier variables can be used for correlation.
For receive events that are triggered using a Service Component
Architecture (SCA) service call, only variables that are marked as process
instance identifiers can be used for correlation. Tip: If a selected variable is
subsequently changed to not be a process instance identifier, an error icon is
displayed by the variable on this tab.
3. To complete the data mapping, click the Auto-map input properties with
variables from service icon ( ) in both the Input Mapping and Output
Mapping sections.Note: Auto-mapping works only when variable names and
498
types match exactly. You should always use an identical name and data type for
a set of input and output variables that are passed in, processed, and then
passed back.
If your variable is a shared business object then the output mapping from the
activity or step is not required.
4. Click Save to save the configuration.
What to do next
The data mapping is complete, and you can test it.
Parent topic:Declaring and passing variables
Related information:
Testing declared variables and data mapping with coaches
499
Procedure
1. Expand your subprocess or event subprocess by double-clicking the activity in the
parent BPD. The contents of your subprocess or event subprocess are visible in
the editor.
2. Go to the Variables tab. The input and output variables declared in the top-level
process are visible, as are any private variables declared in the parent BPD. You
can access these variables from within your subprocess or event subprocess,
passing values between any subprocess activities that might require them. For
example, if you are modeling the Get Customer Order subprocess of a larger
Customer Order Handling process, you might need to access the Customer
Account variable that is declared in the parent process.
3. Create private variables for any data that is used only within the context of the
subprocess or event subprocess and any subprocesses it contains. For example,
the Get Customer Order subprocess might need to use a private variable that is
used to authenticate the customer service representative onto the ordering
system. This data is not needed outside of this part of the larger Customer Order
Handling process, so it is a private variable within the subprocess only. In the
Variables tab, click Add Private.
4. Complete the details of the new variable, including a name, data type, and
description. Note: Variable names declared in a subprocess or event subprocess
cannot be the same as variable names declared in its parent process. If there are
multiple layers of embedding, with subprocesses contained within other
subprocesses, variable names must be unique throughout the entire subprocess
hierarchy. In addition, if you specify a search alias to use for business data in
Process Portal searches, this alias must be unique within the top-level process
and across all subprocesses and event subprocesses under the same top-level
parent.
The new private variable is created. This variable is visible to the subprocess or
event subprocess and any embedded subprocesses or event subprocesses, but
is not accessible by the parent BPD.
500
5. To capture information about your subprocess data at run time, you can enable
automatic tracking of variable data for the subprocess.
A. In the Variables tab, select the variable that you want to track.
B. Under Performance Tracking, select the Track this Field check box.
C. In the Tracking tab, ensure that Enable Autotracking is enabled for the
subprocess. This setting is independent of the setting for the parent process.
Therefore, disabling autotracking in the parent BPD does not disable
autotracking in the subprocess or any subprocess that is contained within that
subprocess.
D. After enabling autotracking and specifying the variables to track, save the
process and send your newly defined tracking requirements to the Business
Performance Data Warehouse. From the IBM BPM main menu, select File >
Update Tracking Definitions.
What to do next
Now that you have declared your private variables, activities within your subprocess
or event subprocess can use these variables to capture business data. If you have
activities inside your subprocess that are implemented by services, you will need to
map the input and output data required by these services, either manually through
the Data Mapping tab, or using the Activity wizard. For more information about
mapping input and output data, see Mapping input and output data for an activity or
step.
501
Procedure
1. In Process Designer, open the BPD that includes at least an activity for which you
established data mapping.
2. For each activity you want to test, add a coach to it and add the controls
representing each variable inside the coach. For example, if you want to test data
mapping between 2 activities that implement their own services, add a coach to
each service and drag all the variables (input and output) available into it.
3. Save by clicking the Save icon.
4. Click the Run Process icon ( ) to run the BPD in the Inspector.Note: If
prompted to switch to the Inspector, click Yes.
5. Check your data mapping with the coaches:
A. In the Process Instances tab in the Inspector, run the current task by clicking
the line of the table on the right side of the screen indicating Received in the
Status column and then click the Run the selected task icon ( ).
B. When prompted, select the user account that you want to use to run the task.
By default, activities in the participant lane are assigned to the All Users
group. The task runs and the coach displays the values of the local variables in
a browser window. The values that are displayed depend on the data mapping
of the current task.
C. Modify the values of the variables to see whether the changes will be passed
on to the next task for which you mapped the data. To validate your changes
click OK. The browser closes.
D. In the Inspector toolbar, click the Refresh icon ( ). The task generated by the
following activity in the BPD is displayed.
E. Repeat the previous steps and check that the current variables displayed in the
browser reflect the changes you made in the previous coach.
502
What to do next
If the data you modify in a task is displayed in the following task of your BPD, your
data mapping is properly set. If the data should match but does not, review your
data mapping settings.
Parent topic:Declaring and passing variables
Related information:
Mapping input and output data for an activity or step
503
</xsd:sequence>
</xsd:complexType>
<xsd:complexType name="BenefitMessagesWrapper">
<xsd:sequence>
<xsd:element maxOccurs="unbounded" minOccurs="0"
504
505
Procedure
1. Declare your BPD-level variables through the graphic interface.
2. Click to select an activity in the BPD diagram or a server script component in a
service.
3. Click the Implementation tab in the properties.
4. If you selected an activity, in the Implementation section, select JavaScript from
the drop-down list.
5. Type your JavaScript code in the Script text box.
Results
Your code is run when you run your process.
What to do next
If you want to reuse your code, you can write your code in an external JavaScript file
and import it as an external library.
Parent topic:Business objects and variables
Related information:
Managing external files
506
Procedure
1. In the Variables tab of your BPD or service diagram, declare a variable that is a
complex business object or a list. For example, a variable named myVariable of
type Requisition or a variable named myList that is a list of string variables.
2. In the diagram area, drag a script task from the palette to the canvas.
3. In the Implementation tab, initialize your variable using the a JavaScript text area:
- If the variable is a complex object, use: tw.local.<variableName>=new
tw.object.<businessObject>();. For example: tw.local.myVariable=new
tw.object.Requisition();
- If the variable is a list, use: tw.local.<listName>=new
tw.object.listOf.<businessObject>();. For example:
tw.local.myList=new tw.object.listOf.String();
Note: If your complex business object or list includes elements that are complex
variables, they also must be initialized.
What to do next
You have initialized your complex variable or list. The variable can now store data.
Parent topic:Business objects and variables
Related information:
Declaring variables for a BPD or a service in Process Designer
507
Procedure
1. Open the Process Designer desktop editor.
2. Expand Data and select Exposed Process Value. The New Exposed Process
Value window opens.
3. In the Name field, type a name for the value and click Finish. The EPV
configuration view opens.
4. Configure the EPV:
A. In the Documentation field, enter a description of the EPV for the developers.
B. To allow users to send feedback about this EPV, type an email address in the
Feedback E-mail Contact field.The Manage Exposed Process Values page in
the Process Admin Console includes a feedback link that uses this email
address.
C. In the External Description field, enter a description of the EPV for the users.
The description that you provide here is displayed in the Manage Exposed
Process Values page in the Process Admin Console.
5. Add one or several variables to the EPV by applying the following steps:
A. In the Exposed Process Value Variables section, click Add to add a variable
to this EPV.For example, if you want to enable users to adjust the dollar
amounts that correspond with various levels of approvers for an expense
reimbursement process, add a variable for each available level.
B. In the Variable Details section, in the External Name field, type the name of
the variable for the users. This name appears in the Variable List for this EPV
in the Process Admin Console.
C. In the Variable Name field, type the name of the variable for internal
processing.Note: Variable names should start with a lowercase letter, with
subsequent words capitalized like so: myVar. Do not use underscores or
spaces in variable names. Variable names are case sensitive.
D. In the External Description field, type the text to describe this variable to
users. This description appears in the Variable List for this EPV in the Process
Admin Console.
508
E. Optional: In the Default Value text box, type a valid default for this variable.
F. To enable in-progress tasks to use the updated value of this variable when
users edits its value, select the In-Progress Tasks Use New Values check
box.
G. To select a variable type, click Select... and select a business object or click
New to create a new custom business object (variable type).
6. In the Exposing section, click Select to choose the team whose members can
manage this EPV and adjust its variable values.
7. Click Save in the main toolbar to save your changes.
Results
The EPV is created, you can link it to a BPD, service, or report.
You can reference the name of the EPV and its variables like so:
tw.epv.[epv_name].[epv_variable_name].
You can use the EPV in a decision gateway to control the flow of a process. You
can also reference the EPV from any JavaScript code in a linked BPD, such as the
code within a server script service component.
509
Procedure
1. Open the BPD or service to which you want to link this EPV.
2. Click the Variables tab.
3. Click Link EPV and select the EPV from the list.
Results
When you run the BPD or service to which the EPV is linked, you can go to the
Process Admin Console to manage the exposed process values.
Parent topic:Creating exposed process values (EPVs)
Related information:
Managing exposed process values (EPVs)
510
Procedure
1. Click the plus sign next to the Performance category in the library, and open the
report to which you want to link this EPV.
2. Click the Overview tab.
3. In the Exposed Process Values section, click Link EPV and select the EPV from
the list.
Results
Now, users can adjust variable values directly from a report.
Parent topic:Creating exposed process values (EPVs)
Related information:
Managing exposed process values (EPVs)
511
Procedure
1. Open the Process Designer desktop editor.
2. Open a business process definition (BPD) that includes an activity or event that
requires a pre assignment or a post assignment.
3. Click the activity or event in the BPD diagram and then select the Pre & Post
option in the properties.
4. To add an assignment, click the Add assignment icon ( ) in either the Pre
Assignments section or the Post Assignments section.
5. In the field on the left, click the variable icon to choose a variable that you have
declared in the current BPD that will receive the value.
6. In the field on the right, type the variable name that will be used as value for the
variable in the left field. Tip: You can type any existing variable name. Use the
type-ahead feature to select your variable, you do not have to limit yourself to
local variables.
When you set a pre or post assignment for an activity, the activity in the BPD
diagram includes a circular indicator on the left side (pre assignment) or on the
right side (post assignment).
Parent topic:Business objects and variables
Related information:
Accessing variables in Process Designer
Creating exposed process values (EPVs)
512
514
Your first decision is whether to use client-side human services or heritage human
services. Client-side human services are the latest technology in IBM Business
Process Manager. Client-side human services are built using the Process Designer
web editor and run in a web browser. Generally, you should use client-side human
services unless one or more of the following conditions apply:
- You are editing a human service that existed prior to version 8.5.5. Human
services in previous versions are now known as heritage human services.
- You are editing a heritage human service that was created in version 8.5.5.
- You want to use some of the features in heritage human services that are not
available in client-side human services, such as collaboration. The collaboration
feature allows multiple users to work on the same coach instance simultaneously.
For information, see Setting up collaboration features for business users.
- You do not need the enhancements and features of the new Process Designer
web editor and you prefer to work in the familiar Process Designer desktop editor
for your process application development.
If one or more of these conditions apply, use heritage human services. Heritage
human services run on the server but display their user interfaces in a web browser.
To create or edit heritage human services you use the Process Designer desktop
editor. Note that a process application can have both heritage human services and
515
client-side human services and both types can use the same coach views.
If you are using client-side human services, you are automatically using coaches
and coach views. Because the stock controls are coach views, you can use these
basic user interface elements to create complex coaches and coach views.
If you are using heritage human services, you then must decide whether to use
coaches or heritage coaches for a particular user interface. A heritage human
service can have coaches and heritage coaches in its flow. Generally, you should
use coaches unless you are updating existing heritage coaches. Heritage coaches
are user interfaces that were created in IBM BPM prior to version 8.0. For these
user interfaces, using heritage coaches means that you are updating the user
interface using the same artifact that was originally used to create it. However, if the
update is extensive in scope (that is, you need to update a number of similar
heritage coaches), consider replacing these heritage coaches with coaches to take
advantage of the reusability of coach views and the stock controls that IBM BPM
provides.
Parent topic:Creating user interfaces for business processes
Related information:
Building heritage coaches
Coaches
Coach views
Controls
Client-side human services
516
Coaches are composed from one or more coach views, which are reusable UI
elements. Coach views can be simple or compound. A simple view contains a single
UI widget such as a text field. The stock controls in IBM Business Process Manager
are examples of simple views. A compound view contains multiple coach views. A
form with multiple text fields and selection controls is an example of a compound
view.
When you are developing applications in IBM Business Process Manager, you
create coaches and views by using the Process Designer web editor for client-side
human services and the Process Designer desktop editor for heritage human
services. Users see and interact with these coaches and views in a web browser
when the human service is running.
- Human services
In IBM BPM V8.5.5, you can use two types of human services to provide user
interfaces that users can use to manage their process and case work in web-based
applications such as IBM Process Portal: heritage human services and client-side
human services.
- Dashboards
A dashboard is a user interface that displays business process information.
Authorized users use the dashboard to interact with that information.
- Coaches
Coaches are the user interfaces for human services.
517
- Coach views
Coach views are reusable sets of user interfaces that users use to interact with a
business object or service. Coach views can consist of one or more other coach
views, data bindings, layout instructions, and behaviors.
- Controls
Controls are basic user interface artifacts such as text fields, date time pickers,
and buttons.
- Advanced items for coach views
Advanced items are palette items that you can add to a coach view to enhance its
content. Unlike most of the items on the palette, advanced items are not coach
views or variables.
- Heritage artifacts
IBM Business Process Manager contains a number of artifacts that are labeled
heritage.
Parent topic:Creating user interfaces for business processes
518
Human services
In IBM BPM V8.5.5, you can use two types of human services to provide user
interfaces that users can use to manage their process and case work in web-based
applications such as IBM Process Portal: heritage human services and client-side
human services.
- Heritage human services
- The human services in IBM BPM versions that are earlier than version 8.5.5.
With heritage human services, you use existing artifacts, such as coaches,
heritage coaches, and stock controls, to create user interfaces for business
process management. You create and edit heritage human services in the IBM
Process Designer desktop editor, run them on the server, and use them to
supply user interfaces to web-based applications such as IBM Process Portal.
- When you build a heritage human service in the Process Designer desktop
editor, you use coaches or heritage coaches, server scripts, services, and
events to create a service flow that is run and tested on the server. The
heritage human services are the only type of human services that can call other
heritage human services.
- Client-side human services
- Human services that are added in IBM BPM V8.5.5. When you use client-side
human services, you can use web technology to improve human-service
performance and provide support for case management and process
management. You create and edit client-side human services in the Process
Designer web editor, run them on the client-side in the web browser, and use
them to call the server for data when necessary.
- When you build a client-side human service, you use coaches, client-side
scripts, services, and events to create a service flow that is run, tested, and
refined entirely in a web browser. Enhanced authoring capabilities such as
WYSIWYG (what you see is what you get) and responsive design elements
help you build user interfaces for case and process instances and ensure
scalability for mobile devices.
To learn more about the differences between the two types of human services, see
Difference between client-side human services and heritage human services.
Parent topic:User interface concepts
Related concepts:
Heritage human service to client-side human service conversion
Related information:
Difference between client-side human services and heritage human services
519
Dashboards
A dashboard is a user interface that displays business process information.
Authorized users use the dashboard to interact with that information.
A dashboard displays data from one or more business processes. Although the
dashboard can display the data in many different ways, typically it uses charts,
graphs, and other visualization user interfaces. A dashboard can also contain other
content.
Using dashboards, users can see an overview of the data or filter it to concentrate
on a particular aspect. If users have the appropriate permissions, they can use the
dashboard to interact with the data. For example, a graph in a dashboard shows all
the business processes. It identifies which processes might need attention because
they have process instances that are at risk or overdue. A process owner can use
the dashboard to identify the problem and then act in a way that enables process
instances to finish on time. Similarly, team leaders can use a dashboard to check
the status of work items and reassign work to balance the workload between team
members.
Users can access a dashboard by using IBM Process Portal. Process Portal
provides access to many dashboards, work interfaces, and user preferences from
one URL. It includes several standard, ready-to-use dashboards that help you
analyze and manage your business processes. These standard dashboards include
the following dashboards:
- Team Performance
- Process Performance
In addition, your Process Portal installation might include company-specific
dashboards to help you manage other aspects of business processes. A business
programmer or analyst creates these dashboards by exposing human services and
by using the Coaches of those human services as the user interfaces of the
dashboard.
If an administrator exposes the dashboard as a URL, users can access the
dashboard outside of Process Portal. Users can also access the dashboard as a
portlet for WebSphere Portal.
Parent topic:User interface concepts
Related information:
Customizing the IBM Business Process Manager dashboards
Dashboards in Process Portal
520
Coaches
Coaches are the user interfaces for human services.
There are two types of user interfaces for human services: dashboards and task
completion. To build either type of user interface for human services, you use
coaches.
When a coach is a dashboard user interface, users can run it as a stand-alone user
interface at any time. The users access it through the Process Portal. For
information about dashboards, see Dashboards in Process Portal. Users can also
access it as a WebSphere portlet. For information, see Generating portlets for
heritage human services exposed as dashboards.
When a coach is a task completion user interface, it is part of the human service
flow. When the flow enters the coach, the user sees the user interface that is
defined for that coach. The user interface consists of HTML code that is displayed in
a web browser. The flow leaves the coach when a boundary event occurs. A coach
can have multiple exit flows with each one associated with a different boundary
event.
Coaches contain one or more coach views. The coach views provide the user
interface elements and layout for the coach. Each coach view can contain one or
more other coach views, which creates a parent-child relationship between these
coach views. At run time, the parent coach view is rendered as a <div></div> tag
that contains a nested <div></div> tag for each child coach view. Each coach view
can also have a binding to a business object, CSS code to control its visual layout,
and JavaScript to define its behavior.
Coach views are reusable so you can create a library of common user interfaces
and behavior. You can combine these common user interfaces to rapidly develop
new coaches. The coaches toolkit that is included with IBM BPM contains
common user interfaces that are called controls. You can include these controls
when you are creating your own coach views.
To maintain compatibility with earlier coaches, IBM BPM supports heritage coaches
only in the heritage human services. No heritage coach support is provided with the
new client-side human services. A heritage coach has the technology and
architecture of a coach in versions of IBM BPM before V8.0. Both client-side human
services and heritage human services can have coaches. Heritage coaches can be
used only with heritage human services; they are not available with client-side
human services. You can continue to use and maintain heritage coaches, but use
coaches for new user interfaces for human services.
521
522
Coach views
Coach views are reusable sets of user interfaces that users use to interact with a
business object or service. Coach views can consist of one or more other coach
views, data bindings, layout instructions, and behaviors.
Because coach views are reusable, coach views and coaches can share parts of
their user interface with other coach views and coaches. For example, you create a
coach that has a coach view that contains a set of address fields. If you create a
second coach that needs address fields, you can reuse the coach view from the first
coach. In both cases, the coach is using an instance of the coach view. You can edit
the properties of each instance independently. For example, changing the label of
one coach view instance does not change the label of the other. Both instances of
the coach view use a reference to point to the coach view definition. This approach
means that if the coach view definition changes, you can see the change reflected in
the instances of the coach view.
You can create a coach view in the process application or in a toolkit. In general,
create highly reusable coach views in toolkits and more specialized coach views in
process applications. Choosing the process application means that you can reuse it
only within the process application. However, it also means that if someone edits the
coach view, the changes apply to the instances of the coach view in the process
application. If the coach view is in a toolkit and then someone edits it, the changes
apply to all instances of the coach view in all applications that use that toolkit.
Because editing a coach definition can affect many instances, be careful in your
changes. For example, deleting a content box in the coach view definition could
mean that coaches or coach views that contain instances of that coach view cannot
display the content that they had defined in that content box.
You cannot directly edit the definition of the coach view from within the parent coach
or coach view. Instead, you must open the coach view definition first before you can
change it. When you open a coach view definition to edit it, you can see the
following pages:
- The Overview page displays the coach view name, information about the coach
view, the images used to represent the coach view during design time, and how
the coach view is used. You can also tag your coach view to make it easier to find
in the library and on the palette.
- The Behavior page displays the scripts and CSS files used by the coach view.
The page also contains inline JavaScript and style code. The Behavior page is
also where you define event handler code. The event handlers are the entry points
for the code of the coach view. While the coach view might reference supporting
JavaScript files, the event handlers contain the functions that the IBM Business
Process Manager framework calls.
- The Variables page displays the business data binding, configuration options
(which includes Ajax services), and localization resources available to the coach
view or used by the coach view.
- The Layout page displays the coach views and controls contained within the
coach view and their relative positions. The layout page also displays the palette,
which contains items that you can add to the coach view. These items consist of
coach views, advanced items, and variables. When you select coach view or
523
524
Templates
Templates are an ideal way to create a standardized look across multiple coach
views.
A template is a coach view that someone marks as being usable as a template in its
Overview page. Users can then select the template when they are creating coach
views. The new coach views have the content of the template as base content to
which the users can then add content. For example, you create a coach view that
has the company logo and name in a banner area and a content box as a
placeholder for other content. When you use this coach view as a template, you can
then select it when you are creating another coach view. The new coach view has
the banner area defined in the template along with an area for content. Other users
can also use the template when they are creating coach views so that there is a
consistent look across the new coach views. Because templates are coach views,
you can also drop them onto coaches. For example, if you have a template that has
a common banner, you can drop it onto a coach so that the coach has the common
banner.
The template also serves as a way to update multiple coach views simultaneously.
Because the template is a reference to a coach view and not a copy, if you change
the template, all of the coach views based on that template are updated as well with
those changes. To continue the previous example, you update the template to
change the logo image. All of the coach views that use your template are updated
with the new logo.
Parent topic:Coach views
Related information:
Example: creating a template
Coach views
525
526
Help
Control ID
Binding
View
Label Visibility
Description
Sets the display name of the coach view.
The location of the label depends on the
coach view type and whether that
location has been overridden by CSS
coding. The default value is the name of
the coach view.
Provides an area in which you can
provide hover help for the coach view
instance
Provides an identifier that you can use in
JavaScript to access this particular coach
view instance. The Control ID is also
known as the view ID in the API
documentation.
Sets the business object or data type that
is associated with this coach view
instance
Sets the coach view definition that the
coach view instance uses. When you
change this property, you change the
type of the coach view, and the
configuration properties that you
previously set no longer apply.
Sets whether users can see the label at
run time. For example, you might want to
have a Text Area control display a large
description with no accompanying label.
The values are Show (default) and Hide.
You can use a variable to, for example,
dynamically change the visibility
according to various conditions. If you
use a variable to set the visibility, the
variable must be a string with one of the
following values: SHOWHIDE.
527
Note: If you assign a variable for the Label, Help, Visibility, and Label Visibility
general properties, a special category of variables, called general options, becomes
available in the configuration options. These variables contain the metadata for the
coach view and correspond to the Label, Help, Visibility, and Label Visibility general
properties. Unlike the other configuration options, you cannot edit their values in the
Variables page.
The Tabs and Table stock controls use the Visibility and Label Visibility properties of
the coach views that they contain to handle hiding labels. These stock controls also
use them to support click-to-edit functionality.
Parent topic:Coach view properties
Related information:
Developing reusable coach views
528
When users click an instance of the coach view, they see the Config group. If
users expand the twistie, they see config1 and config2.
The data type of the configuration option affects how the coach view instance
displays the corresponding configuration property. If the type is a simple type, like
String, or is based on a simple type, the corresponding configuration property is an
appropriate control. For example, the control is a check box for the Boolean type or
text field for a String type. If the type is a business object, the configuration property
529
If the type is a list, the configuration property is a two-column table. Each row in the
table represents an item in the list.
If the type is a list of business objects, the configuration property is a table with a
header row and a row for each list item. Each parameter in the business object has
530
business object.
Here is config6 presented as a configuration table formatted as a three-column
table:
A coach view instance uses implicit default values for configuration properties if
users do not set a value for them. The implicit default value depends on the type.
When you are defining a Boolean-typed configuration option, you must account for
its implicit default value, which is false. This means that Process Designer displays
Boolean-typed configuration options set to false by default, such as check boxes
being not selected.
You can set a configuration option to be responsive to screen size settings, allowing
instances of the coach view can have up to three different settings for that
configuration property, each corresponding to a different screen size setting. For
example, if your coach view has a configuration property that controls the rendering
of a selection control as either a checkbox, radio button, or slider control, users can
configure their coach view instances to have three different renderings for that
control in different user environments. To make a configuration option responsive,
click Responds to screen size.
531
When users are configuring the coach view instance and want to set a different
value for each screen size, they click the screen size icon next to the configuration
option to specify that the value applies to a large, medium, or small screen size.
Then they can change the screen size setting to a new size, and enter a new value
for the configuration option. For information about responsive settings for coach
view instances see Responsive settings for coach views.
When you are setting (binding to data) a configuration property on a coach view
instance, you can bind it statically or dynamically. To bind it statically, type or
choose a value for the configuration property. To bind it dynamically, assign a
variable to the configuration property by clicking . You can then select an existing
variable from the presented list. By default, the list displays all variables. The
variables with a data type that matches the type that is defined for the configuration
options are in bold. However, you can select to display only these variables. If you
select a variable and its type does not match the type that is defined for the
configuration option, the designer displays a warning. Instead of selecting a variable,
you can select to have the designer create a configuration option of the correct
type and bind the configuration property to this configuration option. Restrictions:
- You cannot statically bind to a business object that contains nested lists. Instead,
you must bind to it dynamically.
- If a dynamic value is set for a responsive configuration option instance, only one
value can be chosen. For example, you cannot bind a different variable for each
screen size setting. One exception to this restriction is configuration options that
have a URL type. If these configuration options are set to be responsive, they can
accept values for different screen size settings provided that those values are web
files.
- Only configuration options that are object type can be marked as responsive.
Responsive settings are not supported for service-type configuration options.
532
The margin and padding properties take up to four values, corresponding to values
for the top, right, bottom, and left of the view. If a single value is specified for margin
or padding, it is applied to all four sides. For example, if you specify the view margin
with a single value of 15pt, then the margin on all four sides of the view will be set to
15 pt. To set the values individually for the different sides of the view, you can type
them out individually using the format toprightbottomleft or you can click the
button next to the field to use the dialog to enter values for each side.
533
The values that you specify can be relative or absolute values, depending on the
unit of measurement that you specify. The supported units of measure are described
in the following tables.
Table 1. Relative units of measure
Abbreviation
%
px
em
rem
Description
Percentage of viewport
CSS pixels
Width of letter 'm' in current font
Width of letter 'm' in font of toplevel page element
Description
Inch
Millimeter
Centimeter
Point (1/72 inch)
Pica (12 points)
Coach view positioning property settings follow the same inheritance patterns as
other responsive properties. For example, if you set positioning properties for your
view using the Large screen size setting, these values are inherited by other screen
size, unless you overwrite these values. When looking at the view instance under
another screen size setting, for example, the small screen setting, you can see the
inherited values by default. You can overwrite these values by entering new values
for that screen size setting.
Overflow settings
At run time, the contents of a coach view instance might be larger than the display
area defined by the Height and Width settings for the view. By default, all view
content is shown in the display area. However, in some cases, view content might
overlap, particularly in complex coach views that include other views.
You can optionally configure your coach view to behave differently by setting
Overflow Content to any of the values in the following table.
Table 3. Overflow Content Settings
Value
Show all content (visible)
Hide overflow content (hidden)
Permanent scroll bars (scroll)
Behavior
All coach view content is always
displayed. This is the default
setting.
Any overflow content is not
visible.
Scroll bars always appear with
the coach view.
534
535
You can use a variable to, for example, dynamically change the visibility according
to various conditions. If you use a variable to set the visibility, the variable must be a
string with one of the following values: DEFAULT (the code equivalent of Same as
parent) EDITABLEREQUIREDREADONLYNONEHIDDEN.
you might have two versions of a coach view, one more detailed and one that is
pared down to the barest of information for smaller screen environments. You can
configure the visibility settings on the coach view instances to hide the more detailed
coach view instance in small screen size environments, and show a simplified
version instead.
To specify different visibility settings for each screen size, select the view, click the
screen size icon to specify that the setting applies to a large, medium, or small
screen size, and then enter the visibility settings for that screen size. Next, change
the screen size setting to a new size, and enter new visibility settings for that screen
size setting.
For information about responsive settings for coach view instances see Responsive
settings for coach views.
537
HTML attributes
The HTML Attributes page is where you override styles for a specific coach view
instance.
Overriding a style consists of the following things:
- An HTML class attribute in each coach view instance that you want to specifically
style.
- A corresponding CSS rule for that class attribute.
Important: Do not use the following names as CSS class names in your HTML
source code because they are reserved names:
- CoachView
- ContentBox
For example, text boxes have their labels above the text area. However, you want
the label to be to the left of the text area.
Default label position
3. In any parent coach view, add the CSS rule to a .css file and add that file as an
included script or add the CSS rule directly as inline CSS. If the coach view is a
top-level view in a coach, add a custom HTML item that contains the style rule.
538
539
lists or elements of lists. When you have this arrangement, the list of the container
(outer) coach view controls the repetition. The list of the contained (inner) coach
view provides the contents. For example, you have a section that is bound to a list of
names. The content box for the section contains a Text stock control that is bound to
the currentItem of the list of names. At run time, the section repeats for each name
in the list. Each repeating section contains a field. In the first section, the field
contains the first name. The field in the second section contains the second name,
and so on.
You can bind the outer coach view and the inner coach views to different lists.
However, if you bind an inner coach view to the currentItem of a different list, the
two lists must contain the same number of items. If the two lists do not have the
same number of items, users see a message. The specific message depends on
whether the inner list contains more or fewer items. If the outer list has more items,
the users see some highlighted coach views in the repeated content. They are
highlighted because they do not have data. For example, outerList[] has three
items and innerList[] has two items. The coach views that are bound to
innerList.currentItem repeat three times, but only the first two have data. If the
outer list has fewer items during run time, the user cannot see these excess items
because the inner list has nowhere to display them. For example, outerList[] has
four items and innerList[] has five items. The coach views that are bound to
innerList.currentitem repeat four times. The user cannot see the coach views
for the fifth innerList[] item.
Parent topic:Coach views
Related information:
Coach views
Business objects and variables in Process Designer
Binding data and configuration options
Framework managed versus view managed content for coaches
540
context.binding
The binding object, if defined, provides access to data that is bound to a view. There
is at most one data binding declared for each view.
You can access data that is bound to a view by using the construct:
this.context.binding.get("value"), where value is a special property name
that returns the data binding. For example, if a view is bound to local.
phoneBook.title, then the view can get the phone book's title as follows:
if (!! this.context.binding){
var title = this.context.binding.get("value")
}
The main reason for views to bind to data is so that the view can be notified if the
bound data has been modified. The view framework detects data changes in the
bound object, and automatically notifies the view by calling its change event handler
function. It is important to note that these notifications will be sent to the view only if
the binding object itself changes, but not if any of its properties or sub-properties
change. The following sections discuss the different data types and outline the
cases where additional code is required for the view to receive notification of a data
change.
541
In the example, the view is bound to a complex object and sets a change handler to
be notified if binding.property1.property2 (which is a string) changes. It also
sets another change handler to be notified if any sub-property of property3
changes. In both cases the scope in which the change handler is called is the view's
this scope.
Type
Description
542
listAllSelectedIndices
Array
listAllSelected
Array
listSelectedIndex
Integer
listSelected
Object
The bindAll() function does not include these special properties. To receive
notification of a change in a special property, you can subscribe to the individual
property using the bind() function. In general, it is sufficient to subscribe to one
special property (that is, it is not necessary to subscribe to all of the special
properties). The following example code could be added to a load event handler to
call a view's indicesChanged function whenever the value of
listAllSelectedIndices changes.var binding = this.context.binding.get("value"); //this is a list
this.selectedIndicesHandle = binding.bind("listAllSelectedIndices", this.indicesChanged, this);
List operations
The following APIs are used to modify a list and to get information about a list.
- To add an object, use list.add(item). For example,
-
this.context.binding.get("value").add(item)
To remove an object, use list.remove(index), For example,
this.context.binding.get("value").remove(0)
To replace an object, use list.put(index, item). For example,
this.context.binding.get("value").put(0, item)
To get the length of a list, use list.length().
To get an indexed element or property of the list, use list.get(index |
property). For more information, see Accessing list elements.
Configuration options
In addition to data, views also can be bound to configuration options. A view can
have multiple configuration options. For example, the label of a button control is a
configuration property. The values for the configuration can be retrieved using the
view's this.context.options object. The object context.options contains a
544
Type
String
visibility
String
labelVisibility
String
helpText
String
Description
The label value of the view,
if one exists
The visibility settings for
the view. Valid values are:
"DEFAULT" | "EDITABLE" |
"REQUIRED" | "READONLY" |
"NONE" | "HIDDEN". See
The coach view context
object. DEFAULT is the code
equivalent to Same as
parent that users see on
screen in a Visibility
list.Important: Tables
have a Disable click-toedit configuration property.
The default value is false,
which means that Coach
Views contained within that
table use the visibility
settings of the table. That
is, the Coach Views in a
given cell are READONLY
until the user clicks in the
cell. The Coach Views are
then EDITABLE until the
user clicks anywhere
outside of the cell. The
Coach Views revert to
being READONLY. When
Disable click-to-edit is
true, these Coach Views
use their own visibility
settings.
Important: Setting the
visibility to REQUIRED does
not validate whether a user
has entered or set a value.
You must provide code
that does this checking by,
for example, implementing
a validation service for the
Coach that contains the
Coach View.
The visibility settings for
the label. Valid values are
"SHOW" | "HIDE"
The view can use this
property as hover text
545
className
String
htmlOverrides
Map
Configuration options are accessed and updated in the same way as binding data.
For example:
- To get a view's predefined options, use this.context.options._metadata.*.
For example, to get a view's visibility option, use
this.context.options._metadata.visibility.get("value");
- To set a view's predefined options, use this.context.options._metadata.*.
option name.
- To set a user defined configuration option, use
this.context.options.myOption.set("value", newValue);, where myOption
546
Boundary events
A boundary event acts as a trigger within a human service that sends information
from a client to a server where the information is then committed and the human
service moves to the next step.
You can use named boundary events in both stock views and custom views;
however, only one boundary event can be specified per coach view. The stock
button control views have boundary events specified by default.
When you create a coach view, you specify a boundary event on the Overview tab
under Usage. You must add JavaScript code to trigger the event at the appropriate
time using the this.context.trigger(callback) application programming
interface (API). This code is part of the behavior defined in the Behavior tab of the
view.
Important: When a boundary event has been specified in a coach, the boundary
event must be wired to the next state.
For loopback scenarios where the data is committed and then the same coach
reopens, only the affected data is reloaded in the coach view instead of the full
page.
547
Event Handlers
load
view
548
Description
When the coach is run, the
HTML is generated first
and then the load()
function is called to
perform initialization logic,
such as defining variables.
The load() function is only
called once. For composite
views, during the load()
call, each subview's load()
is invoked before the
composite view's load().
After initialization is
completed, the view()
function is called before
the user sees the view.
The view() function
typically performs logic to
determine what a user
sees when the view is
rendered. For example,
you can show or hide
labels depending on the
visibility setting. Similar to
the load() function, each
subview's view() is invoked
before the composite
view's view()
change
collaboration
validation
unload
549
550
551
552
Controls
Controls are basic user interface artifacts such as text fields, date time pickers, and
buttons.
IBM Business Process Manager provides a number of controls. These controls
are implemented as coach views, which means that they have the same data
binding, variable definition, properties, and layout implementation as other coach
views. However, because they are part of IBM Business Process Manager, the
controls are read only. You can use them but you cannot modify their definition. Like
other coach views, you can modify instances by using configuration properties and
by overriding default styling, for example.
For each control, the data binding is optional. However, if you define a binding for an
instance, it must match the type in the control definition. A warning displays if the
business object type does not match the type of the data binding that is defined for
the coach view. In each control topic, the business object binding table lists the
business object type that is defined for the control.
For each control instance, the configuration properties are optional. If you want to
override the default value, you can provide a specific value or you assign a variable.
As a convenience, you can also expose the configuration property to any coach
view or coach in a human service that contains your view. Exposing the
configuration property creates a configuration option in the current view with
matching binding. You do not have to create the configuration option and bind it.
Parent topic:User interface concepts
Related information:
Configuration properties and configuration options
Coach views
Stock controls
553
554
Content box
A content box is a placeholder for content that the parent coach view or coach
defines.
In the parent coach or coach view, you can add content to the coach view that
contains the content box. For example, you have a coach view for customer
information and you are using this view in a credit application coach. If you put the
fields and controls for a credit application user interface into the customer
information view, it is more difficult to reuse it. You might be limited to reusing it in
other credit application views or coaches. Instead, provide a content box in the
customer information view. In the credit application coach, place the extra fields and
controls that are needed for the credit application into the content box. By providing
a content box, the parent coach has an area for its specific content and the
customer information view can remain generic. Because the customer information
view is generic, you can reuse the customer information view in other views and
coaches.Table 1. Content box in a coach view and in a parent coach
Coach view
In the coach view itself, you cannot drop anything into a content box. When you
open a view or coach that uses the content, you can drop palette items into the
content box. Additionally, the content that you drop is specific to that instance of the
view. For example, if the parent view or coach contains two instances of the view,
the elements outside of the content box are the same. However, the content boxes
of the two instances are independent; therefore, updating one instance does not
affect the other instance. This rule applies whether the instances are in the same
parent view or in different parent views.
You cannot add a content box to a coach.
Parent topic:Advanced items for coach views
Related information:
Framework managed versus view managed content for coaches
555
556
Custom HTML
By using a custom HTML item, you can add HTML code to a coach or coach view.
The custom HTML item can contain one or more sets of HTML elements such as
<div> and <label> tags. You can add the HTML code directly as text by using a
managed file or by using a variable. The custom HTML item inserts the elements
inside the <div> tag of the coach or coach view. If you are using a custom HTML
item in a container such as the table, tab, horizontal section, and vertical section
stock controls, wrap the HTML code in a <div> tag. By wrapping the HTML code,
the container treats all the HTML code as one entity.Note: When building Coaches
using custom HTML blocks, ensure that the HTML segments within these blocks are
not too large. Custom HTML blocks are designed for use with small to moderatesized HTML segments. If you provide an HTML segment that is too large, you might
see a stack overflow exception. In this case, you should reduce the size of the
HTML segment that you are using within your Coach. See Configuring the JVM in
the WebSphere Application Server product information.
Restriction: If your custom HTML item is within a repeating control such as a table
or section, do not bind it to a variable that is a property within a list item. Normally,
the code generator inserts the custom HTML contents as HTML code when it
creates the page. However, repeating controls are bound to a list. Because the list
contents are not set until runtime, the code generator cannot determine the index of
the variable in the list when it creates the page. If you want text that changes
dynamically, consider using a control such as Output Text that is bound to the
variable.
Important: Do not use the following names as CSS class names in your HTML
source code because they are reserved names:
- CoachView
- ContentBox
The custom HTML item supports the use of JavaScript variables for simple types.
When the server generates the HTML page for the client, it replaces the variable
name with its value. However, after the server generates the page, it does not
update the HTML if there is a change in the value. The server updates the variable
only when it regenerates the entire HTML page. If the server cannot resolve the
variable, users see the variable name instead of its value.
In the code, you wrap the variable in double curly brackets. For coaches, the
variable can refer to the data in the tw.local namespace only. That is, the variable
can refer to the data that is defined in the Variables page of the human service
under the local node. For example, a coach has a user business object variable
with a name parameter that contains the name of the user. You can have the coach
display the name with the following code in an HTML item:<div>Hello,
{{tw.local.user.name}}.</div>
For coach views, the variable can refer to the data in the tw.businessData or
tw.options namespaces. That is, the variable can refer to the data that is defined
in the Variables page of the view under the Business Data or Configuration Options
557
nodes. For example, if you want to have a view display the name of a street, you
bind the view to a address business object with a parameter named street. In an
HTML item, you add the following code:{{tw.businessData.address.street}}
If you place an instance of that view into a coach, the user sees the value of the
street parameter in the view. However, if the user updates the street parameter,
the contents in the HTML item do not update until the server regenerates the entire
page.
Tip: To insert a script, add the script using inline scripts on the Behavior page of the
view. Do not add the script using a custom HTML item.
558
Heritage artifacts
IBM Business Process Manager contains a number of artifacts that are labeled
heritage.
A heritage artifact is a technology that belongs to a previous version of IBM
Business Process Manager but remains supported in the current version, although a
newer version of the artifact using a different technology is available. The heritage
artifact remains supported in the current version until IBM identifies it as deprecated
or removed. IBM Business Process Manager uses heritage artifacts to support
existing process applications so that there is no need to upgrade them. While you
can develop new applications by using heritage artifacts, the recommended
approach is to use the new replacement artifacts to take advantage of their
enhancements.Important: Heritage artifacts are not necessarily directly compatible
with artifacts in later versions. See the limitations in the table of heritage artifacts for
information.
The following table lists the heritage artifacts, the artifacts that replaced them and
when the replacement occurred, and limitations that apply with using the heritage
artifact.
Heritage artifact
Heritage coaches
Current artifact
Coaches and coach
views in version
8.0.0.0
Heritage human
services
Client-side human
services in version
8.5.5.0
Limitations
Heritage coaches
(pre-8.0.0.0
technology) cannot
be added to clientside human services
(8.5.5.0 technology).
However, process
applications can
contain both heritage
human services and
client-side human
services, and
heritage human
services can contain
heritage coaches.
Calling another clientside human service
or heritage human
service from within a
client-side human
service is not
supported.
560
Usage of JavaScript
562
563
services. A heritage human service flow can mix coaches and heritage coaches so
that one type can flow into the other. However, a coach cannot contain heritage
coach elements, and heritage coaches cannot contain coach views. That is, a user
interface for a heritage human service must be a coach or a heritage coach, but not
a mix of the two.
Visually, coaches resemble heritage coaches in heritage human service diagrams
and on the palette.
Coach
Heritage Coach
When you open or edit a coach, you can see the user interface and palette for IBM
BPMV8.5.5. Heritage human services that were created in earlier versions can
continue to use their existing heritage coaches. You do not need to migrate your
heritage coaches. When you open or edit a heritage coach, you can see the user
interface and palette from V7.5.1. When you open a coach to edit it, you might
notice a number of key differences from the earlier heritage coach:
- The palette contains coach views that you can drop into the coach. Although some
stock controls and other palette items have the same name in heritage coaches,
these items are implemented differently.
- The palette uses tags to categorize the coach views that are available. You can
use the filter to show or hide the categories of coach views.
- The properties area for coach views has different pages from the properties area
for heritage coach controls and sections. However, many of the properties in
heritage coach controls have a corresponding property in coach views. For
example, the page that is named after the heritage coach control contains
properties such as Label, Binding, and Control Id. In coach views, you can find
corresponding properties on the General page. Many of the heritage coach
presentation properties have a corresponding coach configuration option. Even
when heritage coach controls and coach views have properties that have the same
name, the implementation of those properties can be different.
564
by using a client-side human service. To create a client-side human service for the
implementation of your activity, use the Activity wizard.
- Declaring variables for client-side human services
For each client-side human service that you create, you must declare variables to
capture the data that steps or activities in that service flow use.
- Calling another service from a client-side human service
You can call a IBM BPM service from within your client-side human service by
adding an activity to the service flow. This activity calls another service that you
can specify. The called service cannot be another client-side human service or a
heritage human service.
- Implementing exclusive gateways in client-side human services
An exclusive gateway controls the divergence of a sequence flow by determining
the branching of the paths that the flow can take at run time. When you add an
exclusive gateway to your client-side human service, you model a point in the
execution of the service flow where only one of several paths can be followed,
depending on a condition.
- Saving the state of a client-side human service during execution
To allow runtime users to save the state of a partially completed task, you can
enable the execution context to be saved. By enabling the execution context to be
saved, you enable a user who starts working on a task that includes multiple steps
to close the browser and resume work later without losing work.
- Validating client-side coaches using client-side validation
To ensure that a coach that is in your client-side human service passes valid data
in the flow, use the coach validation pattern to check its data.
- Validating client-side coaches using server-side validation
You can validate coaches in client-side human services using server-side
validation.
- Handling errors in client-side human services
To catch errors in client-side human services, you can use intermediate events
that can be attached to service nodes.
- Exposing client-side human services
In addition to implementing activities in a business process definition (BPD) or a
case type, other people can use the client-side human services that you create in
IBM Process Designer to create custom dashboards for IBM Process Portal or
instance user interfaces for case instances. Or they can be exposed as URLs.
- Adding HTML meta tags to client-side human services
To optimize your HTML pages for being viewed on a mobile device, you can
define HTML meta tags in the underlying client-side human service. The HTML
meta tags are added to the HTML header when the client-side human service is
run.
- Enabling work to be postponed and resumed at run time
If you want to enable Process Portal users to postpone and resume work at run
time, you can add a postpone event to the client-side human service flow. The
postpone event can be used only with client-side human services that implement
tasks within a BPD or case type.
- Navigation options for after service completion
To help the user go to a specific page after the client-side human service
completes, you can configure the end event of the service to provide an alternative
566
destination.
- Running and debugging client-side human services
When you author a client-side human service, you use the Inspector in IBM
Process Designer to iteratively test and observe how the client-side human service
behaves at a detailed level. The Inspector can also be used for problem
determination and to identify the source of errors.
- Keyboard accessibility for client-side human services
In the Process Designer web editor, you can perform many actions by using builtin keyboard accessibility features. The keyboard accessibility features help you go
to and edit client-side human service diagrams in the web editor without using the
mouse.
567
Tool name
Coach
Client-side script
Service
Exclusive gateway
568
Description
Use a coach to implement
the user interfaces that are
displayed when you run
the client-side human
service. For more
information, see Building
coaches.
Use a client-side script
when you want to add
JavaScript code to run on
the web browser in the
client-side human service
context, for parsing
variables, and running
programmatic commands.
Use a service to call
another service from within
a client-side human
service. The called service
adds an activity to the
service flow, which calls
another service that you
can specify. The called
service cannot be another
client-side human service
or a heritage human
service. For more
information, see Calling
another service from a
client-side human service.
Use an exclusive gateway
to model a point in the flow
execution where only one
of several paths can be
followed, depending on a
condition. For more
information, see
Implementing exclusive
gateways in client-side
human services.
End event
569
Intermediate event
570
571
Procedure
1. Open the Process Designer desktop editor.
2. Open the appropriate process application in the Designer view.
3. In the library, click the plus sign next to User Interface and, under New, select
Client-Side Human Service, complete the fields and click Finish. The new
client-side human service opens in the web editor in the form of a diagram
exposure in the Overview page of the service.If you are building the client-side
human service in a toolkit instead of in a process application, you can expose
the client-side human service as a dashboard in Process Portal. For more
information, see Exposing client-side human services.
Parent topic:Modeling client-side human services
Related tasks:
Creating case user interfaces
Related information:
Tools available from the palette for client-side human services
Declaring variables for a human service
Building coaches
Creating user interfaces for a BPD
Running client-side human services
Debugging client-side human services
Exposing client-side human services
Activating snapshots for use with IBM Process Portal
Creating, changing, and deleting a toolkit dependency in the Designer view
573
Procedure
1. Open the Process Designer desktop editor.
2. Open the BPD in the Diagram view.
3. Right-click the activity that you want to work with and select Activity Wizard.
4. Complete the Activity wizard. The new client-side human service, which includes
a coach by default, is created and attached to the activity.
5. Double-click the activity for which you created the client-side human service. The
new client-side human service opens in the web editor in the Diagram view.
6. Click the Coaches tab and then click the listed coach. The coach designer is
where you customize the coach layout and create or edit the bindings that are
between inputs and outputs. Notice that when the coach designer is open, the
Palette view shows all the elements, sections, and controls that you can use in a
coach. For more information about the coach designer, see Building coaches.
7. In the coach designer, add controls and buttons to the coach, as required by your
client-side human service.
8. Click Save all in the main toolbar to save your work.
What to do next
To run the client-side human service in the web browser, click Run
Parent topic:Modeling client-side human services
574
Description
Local variables that are used only within
the client-side human service.
Variables that represent input data
passed to the current client-side human
service.
Variables that represent output data that
the current client-side human service
returns to its caller.
Procedure
To add a private, input, or output variable to the client-side human service, complete
the following steps:
1. Open your client-side human service in Process Designer.
2. In the Variables tab, click the plus sign next to Input to add a new input variable.
3. In the Details section:
A. Type a variable name in the Name field.Note: Variable names start with a
lowercase letter, with subsequent words capitalized, for example: myVar. Do
not use underscores or spaces in variable names. Variable names are casesensitive.
B. Click Select next to Variable Type to select the type of the variable from the
Select Library Item list. Custom business objects that you created are also
listed. If you want to create a new business object, click New and complete the
wizard steps.Note: Client-side human services do not support business object
instances that reference themselves. For example, the following JavaScript
generates an error when used inside a client-side human service:
tw.local.myVariable= {};
tw.local.myVariable.pointer= tw.local.myVariable;
What to do next
The client-side human service includes variables that can be passed to activities by
575
576
tw.system.processApp.id
tw.system.processApp.name
tw.system.processApp.acronym
tw.system.processApp.snapshot
tw.system.processApp.snapshot.id
tw.system.processApp.snapshot.name
tw.system.processInstance
tw.system.processInstance.id
tw.system.processInstance.name
Description
The process application or toolkit that
contains the client-side human service.
The identifier of the process application
or toolkit that contains the client-side
human service.
The name of the process application or
toolkit that contains the client-side human
service.
The acronym of the process application
or toolkit that contains the client-side
human service.
The snapshot of the process application
or toolkit that contains the client-side
human service.
The identifier of the process application
or toolkit snapshot that contains the
client-side human service.
The name of the process application or
toolkit snapshot that contains the clientside human service. This variable applies
only if this is a named snapshot.
The process or case instance in which
this client-side human service is running.
This variable applies only if the clientside human service is running in a
process or case instance.
The identifier of the process or case
instance in which this client-side human
service is running.
The name of the process or case
instance in which this client-side human
service is running.
577
tw.system.processInstance.atRiskDate
tw.system.processInstance.dueDate
tw.system.processInstance.startDate
tw.system.processInstance.caseFolderId
tw.system.processInstance.process
tw.system.processInstance.process
tw.system.processInstance.process.nam
e
tw.system.processInstance.process.desc
ription
tw.system.processInstance.task
tw.system.processInstance.task.id
tw.system.processInstance.task.subject
tw.system.processInstance.task.narrative
tw.system.processInstance.task.atRiskD
ate
tw.system.processInstance.task.dueDate
tw.system.user.id
580
581
Procedure
1. Open the appropriate process application in the Designer view.
2. In the Process Designer library, click User Interface and open the client-side
human service that you want to work with, or build a client-side human service as
described in Building a client-side human service. The client-side human service
opens in the web editor.
3. In the Diagram view, use the Service tool
from the palette to add an activity
to the service flow, and wire it as required.
4. Click the new activity in the client-side human service diagram to open the
activity. In the Properties view, in the Implementation tab, click Select and
specify the service to be called by the selected activity.Note: If the client-side
human service is used as an instance details user interface for a BPD or case
type, the Implementation tab provides the following options under Behavior:
- Send the variable updates to the process or case instance: If your clientside human service modifies the values of its input variables at run time, you can
select this option to update the process or case instance variables with the latest
variable values in the client-side human service.
- Refresh the process or case instance variables: If updates to the process
instance variable values are made at run time, you can select this option to
refresh the variables with the last saved variable values from the client-side
human service. Also, select Map input data automatically if you want the input
variables be mapped automatically in the client-side human service, or clear the
check box and go to the Data Mapping tab in the Properties view to enter the
data mapping yourself.
For more information, see Creating user interfaces for a BPD or Creating case
user interfaces.
5. On the Data Mapping tab, set the input and output mapping for the servicecalling activity.
6. Click Save all to save the configuration of the client-side human service.
Parent topic:Modeling client-side human services
582
583
Procedure
1. Open the appropriate client-side human service in the Designer view.
2. In the Diagram view, drag the Exclusive gateway tool
from the palette onto
the diagram.
3. Wire the gateway in the service flow to create the required sequence flow to and
from the gateway, as shown in the following example:
The default sequence flow, which is marked with a forward slash (/) sign on the
diagram, is the first sequence that you create from the gateway to a following
activity.
4. Click the gateway in the diagram. In the General properties, under Common,
specify a name and provide a description for the gateway.
5. Click the Implementation tab. Under Decisions, specify a condition (in
JavaScript) for each outgoing sequence line to control which path is followed.
6. Ensure that the default sequence flow under Default Flow is the one that you
want the flow to follow if all conditions evaluate to false. If not, in the list select the
584
sequence flow that you want to designate as the default sequence flow.Note: The
default sequence flow does not have a condition.
7. Click a sequence line and verify its implementation on the Flow tab. If you do not
want the sequence line name to be displayed in the diagram, under Common
clear Name Visible.
8. Click Save all in the main toolbar to save the gateway configuration.
Parent topic:Modeling client-side human services
585
Procedure
1. In Process Designer, open the client-side human service that you want to model
in the Diagram view.
2. In the diagram, select a point in the service flow where you want users to be able
to save the current progress. For example, you can choose to allow users to save
the execution context between two coaches, as illustrated in the following image,
so that they can complete one page and come back to the next page later:
Tip: To avoid network overhead, enable users to save the execution context only
at key points of the client-side human service.
586
587
Procedure
To validate a coach in your client-side human service, complete the following steps:
1. Open the client-side human service that contains the coach to be validated.
2. Add the following elements to the diagram to create a validation pattern:
- A client-side script to contain the code that performs the validation
- An exclusive gateway to route the flow according to whether the data is valid
- A stay on page event to return the flow back to the coach when the coach data
is not valid
3. Make the following connections:
- Connect the boundary event of the coach to the script.
- Connect the script to the exclusive gateway.
- Connect gateway to the stay on page event. Ensure that this line is the default
flow for the decision. Select the flow line and rename it to Yes.
- Connect gateway to the rest of the human service flow. Select the line and
rename it to No.
The following screen capture shows the validation pattern. In the screen capture,
the non-default branch connects to an end event. This branch of the gateway
could connect to another coach, to another gateway, or any other diagram
element.
Tip: You can have multiple boundary events with each one leading to a different
validation script. The validation scripts can flow to the same exclusive gateway to
588
String errorMessage) JavaScript API to identify the coach view that has the
problematic data and provide a message that helps the user correct the problem.
For example:if (tw.local.startDate.getTime() > tw.local.endDate.getTime())
tw.system.coachValidation.addValidationError("tw.local.startDate", "The start date must precede the end date. Set the
start date before the end date, and try again.");
Note:
- If the data element that is being validated is not bound to a coach view, there is
nowhere to display a validation error if one occurs.
- If a coach view that is being validated contains rich text, the validation script
must remove the formatting before validating the contents.
- If you are validating a list and you want the error to refer to the entire list, the
variableName parameter must include [] as a suffix. This matches coach view
binding where [] indicates that the object is a list. For example, if a coach view
is bound to tw.local.var3[], which is a list, you need code like the following
example: tw.system.coachValidation.addValidationError("tw.local.var3[]", "Var3 has validation error");
Tip: To reuse validation logic, you can define it once then call that logic multiple
times To reuse the validation logic, add a script element to the diagram to contain
the shared logic. Typically, you place this as the first element in the flow. In the
script element, add a function such as the following example: tw.local.validationFn =
function validateCutomerAndOrder ( ) {
// Shared logic goes here.
}
In the validation scripts, call the function using code such as:tw.local.validationFn();
5. Select the exclusive gateway and, in its Implementation properties, create the
test. The test is tw.system.coachValidation.validationErrors.length==0.
The test checks for the presence of validation errors and, if there are none, routes
it to the rest of the flow. If there are errors, the flow goes to the stay on page
event so that the coach can show the control with the problematic data and a
message.
6. Save your changes, and then click Run .
7. In the browser, test that the coach validation works correctly. At run time, the flow
must go first to the validation script to do the coach data validation:
- If the data is valid, the flow moves to the next node.
- If the data in the coach is not valid, the coach validation pattern loops the flow
back to the coach. Error information is passed to the coach, which indicates the
control with the problematic data and can display the image.
589
590
Procedure
To validate a coach by using server-side validation:
1. Open the Process Designer desktop editor.
2. Create the service that validates the coach data. The service cannot be a human
service but it can be any other type. The example code uses a general system
service called Save Ticket Service.
A. In the Variables page, create an input variable that contains the data from the
coach
B. Create the validationResults(CoachValidation) private variable to
contain any validation messages.
591
F. Add JavaScript code to the script to validate the coach data. The script code
must create a CoachValidation object that contains an
addCoachValidationError instance for every problem with the coach data. If
there is a problem with the coach data, the script must also set isValid to
false. For example, if the help ticket must contain information in the Summary
field, add code like the following example:// Create the CoachValidation object
tw.local.validationResults = new tw.object.CoachValidation();
tw.local.hasValidationErrors = false; // Set to false unless the data fails a validation test
if (tw.local.ticket != null) {
// If there is nothing in the summary, add the error to the Coach Validation object
if (tw.local.ticket.summary == null || tw.local.ticket.summary.length == 0) {
tw.local.hasValidationErrors = true;
tw.system.addCoachValidationError(tw.local.validationResults,
"tw.local.ticket.summary", "The problem summary is required.");
}
}
G. In the Implementation properties of the decision, add the following code to the
No branch:tw.local.hasValidationErrors == true
H. In the Implementation properties of the error end event, set Error code to
coachValidation and set Error mapping to the
592
3. Open your client-side human service. The Process Designer web editor displays
the human service.
4. In your client-side human service, add a service to your diagram and wire your
coach to the service.
6. In the Data Mapping properties, map the variable that contains the coach data to
the appropriate business object.
7. Add an intermediate event to the service. Because it is attached to a service, the
intermediate event is an error boundary event.
8. In Implementation properties of the error boundary event, set it to catch specific
errors and map the error data to the tw.system.coachValidation variable.
9. Connect the error boundary event to a stay on page node.
593
Error event
Error boundary event that
is attached to a service
node in a client-side
human service
Description
Catches errors and
receives error data from
the service to which it is
attached.
When you plan to use error events in your client-side human service, consider the
following points:
- You can attach error boundary events only to service nodes in your client-side
human service.
- You can reposition an error boundary event inside the service, you can remove it
from the service, or you can move it to another service. In client-side human
services, the error boundary event cannot exist as a stand-alone error event
outside of a service node.
- Consider specifying the error properties to catch specific errors, filtering on the
error code for the types of errors that are caught, and mapping to a variable after
the errors are caught.
- The error event information is captured in the tw.error.code and tw.error.data
variables.
- By mapping the error boundary event to a variable, events with incompatible data
types are filtered out and the data is captured in a local variable.
For reference information, see JavaScript API for client-side human service
authoring.
Procedure
To add an error boundary event to a service in a client-side human service:
1. Open the Process Designer desktop editor.
2. Open the client-side human service that you want to work with.
594
4. Select the error boundary event and, in its Implementation tab, under Event
Properties, select Catch all errors or Catch specific errors to specify what type
of errors you want the error event to catch.
5. If you selected Catch specific errors, click the pickers next to Error code and
Error mapping to filter on the error code for the specific errors that can be
caught, and map the error data to a local variable.
6. Connect the error boundary event to the logic you want to run when the error
occurs. For example, you can connect it to a coach that displays an error
message to a user.
7. Click Save all to save the configuration.
Parent topic:Modeling client-side human services
Related information:
Validating client-side coaches using server-side validation
Validating client-side coaches using client-side validation
595
Procedure
1. In the Process Designer library, click the plus sign next to User Interface and
create a client-side human service, or click User Interface and select an existing
client-side human service.
2. On the Overview tab of the client-side human service, under HTML Meta Tags,
select the meta tag that you want to add, and enter the corresponding tag
content.
3. In the list of available meta tags, select the check box to turn on a meta tag or
clear the check box to turn off the meta tag.
4. Click Save all to save the configuration of the client-side human service.
Parent topic:Modeling client-side human services
596
Procedure
1. Open the Process Designer desktop editor.
2. Open the client-side human service that you want to work with.
3. In the Diagram view, click the Intermediate event tool
on the palette and drag
the event onto the diagram. The default implementation of the intermediate event
is a stay-on-page event.
4. Select the intermediate event and, in its Implementation tab, under Event Type,
select the postpone event
.Tip: If the postpone option is not available under
Event Type, check your exposure setting on the Overview tab. The postpone
event is only available when you selected Do Not Expose (Service contained in
a BPD or case type). See Exposing client-side human services.
5. In the diagram, connect the postpone event to the node where you want the task
work to be postponed, and add an outgoing connection from the postpone event
back to the node where you want work to be resumed later.
6. Select a navigation option for the postpone event, which determines what the
user will see after the service is postponed. In the Implementation tab of the
597
postpone event, under Event Navigation, select one of the following options:
Table 1. Navigation options available for postpone events
Option
Default (behavior provided by the
hosting UI)
Go to the instance details UI
Go to a specified URL
Description
Go to the default page provided by the
hosting user interface, such as Process
Portal.
Go to the instance details user interface
for the case or process instance within
which the client-side human service is
running.
Specifies a relative URL to go to when
the service is postponed. The URL is
relative to the hosting user interface
such as Process Portal. Because the
URL is specified as a JavaScript
expression, surround any literal values
with quotation marks.
598
599
600
Procedure
1. Open the client-side human service that you want to run.
2. Click Run
in the upper-right corner. The playback window opens, showing the
running client-side human service.
3. If the running activity is a coach, the playback window shows the coach.
Complete the coach and trigger the boundary event to transition out of the coach
and move to the next step in the flow.
Results
The playback window displays a confirmation message that the client-side human
service completed successfully.
Parent topic:Running and debugging client-side human services
601
Action
Step Over
Step Into
Description
Move the service execution
to the next activity in the
flow.
Stop the service execution
on a breakpoint before a
coach is run and debug the
coach.
Bring forward or reopen
the playback window.
Refresh the content of the
service flow with the latest
updates.
Cancels the current
debugging session before
the client-side human
service reaches the end.
Procedure
1. Open the client-side human service that you want to debug.
2. Click Debug
in the upper-right corner. The Inspector opens in the browser
window, pausing on the first step after the Start event.
602
3. Examine the variable values to determine whether they are expected. When you
are ready to move on to the next activity in the client-side human service, click
Step Over .
4. If this activity is a coach, the playback window shows the rendering of the coach.
Complete the coach and trigger the boundary event to transition out of the coach.
The Inspector moves to the next step in the service flow. As the execution
progresses, the followed path is highlighted and color-coded indicators are added
to the client-side human service diagram to mark the progress in the execution.
5. If errors occur while running the coach, use the Step Into action to debug the
coach:
A. Ensure that the playback window is open. Click Show Playback Window to
open it if it is not already open.
B. Open the debugging window or the developer tools that are associated with
the playback window. For information about how to open and use the browser
debugger or developer tools, consult the documentation for your browser.
C. Click Step Into to pause the execution flow before the coach is run. Use
your browser debugger or developer tools to set breakpoints in the source
code for the coach.
D. Go step by step through the code to observe how it behaves and identify any
errors.
When the coach completes successfully, the execution moves to the next step in
the flow.
6. Repeat steps 3 to 5 until you complete the client-side human service.
Alternatively, you can click Cancel Debugging Session to cancel the
debugging session before the client-side human service reaches the end.
7. When you are ready to return to the Designer perspective, click Designer in the
upper-left corner of the browser window.
Parent topic:Running and debugging client-side human services
Related information:
Tips for debugging coach view lifecycle method inside Human Services
Tips for debugging coach views in Process Portal
603
Error: The
\"${MODEL_ID}\" model
from the
\"${BRANCH_ID}\"
branch could not be
loaded. Contact your
system
administrator.Error:
The \"${MODEL_ID}\"
model with the
\"${SNAPSHOT_ID}\"
snapshot ID could not
be loaded. Contact
your system
administrator.
604
Description
A JavaScript error
occurred. The system
administrator can enable
tracing and check the
browser console for
additional information.
The specified model could
not be loaded from the
repository. The system
administrator must verify
that the specified model
values are correct and that
the model is present in the
repository.
HTTP error
Error: The
\"${MODEL_ID}\" model
in the
\"${BRANCH_ID}\"
branch contains no
start nodes. Correct
the model and try
again.Error: The
\"${MODEL_ID}\" model
with the
\"${SNAPSHOT_ID}\"
snapshot ID contains
no start nodes.
Correct the model and
try again.Error: The
\"${MODEL_ID}\" model
in the
\"${BRANCH_ID}\"
branch is invalid
because it does not
contain the
\"${ELEMENT_NAME}\"
element. Correct the
model and try
again.Error: The
\"${MODEL_ID}\" model
with the
\"${SNAPSHOT_ID}\"
snapshot ID is invalid
because it does not
contain the
\"${ELEMENT_NAME}\"
element. Correct the
model and try again.
Server Error (401):
Insufficient
credentials to access
the URL \"${URL}\".
Verify that you have
sufficient
authorization to
access the specified
URL.Server Error
(404): The system was
unable to access the
URL \"${URL}\".
Contact your system
administrator to
ensure that the server
is running.The server
responded with an
error code ${STATUS}
when accessing the URL
\"${URL}\". Contact
your system
administrator.
605
606
Keyboard shortcut
Delete key or Backspace
key
Arrow key
Move all
Select
Spacebar
Select all
Ctrl+A
Multiple select
Ctrl+Spacebar
Clear selection
Esc
Connect
Switch modes
F9
607
Description
Delete the selected node
or connection.
Move the selected node on
the canvas in the direction
that is specified by the
arrow.
Move all the graphical
elements in the diagram in
the direction specified by
the arrow, regardless of
whether they are
connected.
Select the node or
connection that has the
focus.
Select all the graphical
elements that are in the
diagram.
Add or remove the focused
node or connection to or
from the current selection.
Clear the current selection
and the currently focused
node or connection.
Connect two selected
nodes.
Switch between the edition
mode and navigation
mode.
F8
Save
Undo
Ctrl+S
Ctrl+Z
Redo
Open inline editor
Ctrl+Y
F2
Zoom in
Ctrl+Plus(+)
Zoom out
Ctrl+Minus(-)
Zoom reset
Ctrl+0
609
Procedure
To add nodes to the client-side human service diagram by using the keyboard,
complete the following steps:
1. Open the Process Designer desktop editor.
2. Open the client-side human service that you want to work with.
3. In the Diagram view, ensure that the focus is on the canvas, and then press the Q
key. If necessary, use the Tab key to bring the focus back to the canvas. The
Quick Add window opens.
4. Enter the node types that you want to add, separated by pressing Enter, and then
click Add.The types of nodes that are available for you to quickly add to the
canvas match the tools in the palette.Table 1. Node types that are available for
you to quickly add to a client-side human service
Node type
coach
script
service
exclusive
end
intermediate
Description
Add a coach.
Add a client-side server script.
Add an activity that calls another
service.
Add an exclusive gateway.
Add an end event.
Add an intermediate event. The default
implementation is a stay-on-page event.
For an entry that does not match any of the node types that were listed
previously, a client-side script is added to the diagram.
5. In the Properties view of each newly added node, update the node name and its
properties as required.
610
6. Click Save all to save the configuration of the client-side human service.
Parent topic:Keyboard accessibility for client-side human services
611
612
- Server-side validation
- If you used a validation service to validate your coach output, continue using it.
However, modify it to include an error end event that passes the validation
errors back to the client-side human service. See Example: validating a coach
in a heritage human service.
If you instead used a server script to validate your coach logic, you have two
choices:
- If the server script logic includes complex operations or requires access to
private or confidential data, create a general system service with a server
script that holds your logic and use it as described earlier.
- If your server script logic requires simple access to local variables and does
not require access to private or confidential data, create a client-side script in
your client-side human service, and place your validation logic there. See
Example: validating data in a coach that is used in a human service.
Tip: For optimal performance, combine multiple service calls where possible.
For example, instead of calling a validation service followed by a service that
performs some work, combine these into a single service that internally
performs the validation and, if the validation succeeds, performs the work.
- Heritage coaches
- Support for heritage coaches is not provided in client-side human services. For
heritage coaches, continue using the heritage human services that provide the
required support.
- Server integration
- To migrate integration elements such as Invoke UCA or Intermediate Tracking
Event from an existing heritage human service to a new client-side human
service, create an integration service that contains these constructs, and then
call this integration service in the new client-side human service.
613
Building coaches
You can build a coach as the user interface that process participants or case owners
use to interact with a service.
In the first stage of designing a coach, your goal might be to build a mock-up. The
mock-up contains static elements to visualize what data the coach needs at run time
and where the coach displays the data in its layout. After you complete the first
stage to design the look of the coach, you then feed real business data to the coach
controls. This step requires you to create bindings between the coach controls and
the data structures (variables) that represent the business data in your IBM
Business Process Manager processes or cases. Your process participants or case
owners can then interact with the business data, which helps them make the
appropriate decisions.
Building a coach is often an iterative process in which you loop back to refine the
coach as you build it. Although you can do some of the steps in any order, in
general you take the following steps:
1. Create one or more mock-ups for the coach. Use the mock-ups to identify
elements in the coach that are common with other coaches. Identify the
following information:
- The elements in the coach that are reusable.
- The best layout for the user interface elements in the coach.
You can then use this information to decide which parts of the coach you can
implement as reusable coach views. For example, after you create the mock-up,
you see that your coach contains two sets of identical address fields. Instead of
creating the two sets of address field in the coach, you create one address field
coach view. You can then use it for both sets of address fields.
2. If there are toolkits that contain artifacts that your coach can use, add a
dependency to these toolkits. These artifacts include business objects, coach
views, and files. The dependency is to a particular snapshot of the toolkit. If you
are revising an existing coach, you can upgrade the dependency to a different
snapshot of the toolkit. The upgrade is optional. If you do not do the upgrade,
the coach continues to use the existing dependency.Important: The coaches
8.5 toolkit uses Dojo 1.8.6 with AMD (Asynchronous Module Definition). If you
upgrade the coaches toolkit to version 8.5.0, review the coaches in the process
application to assess the impact of the upgrade in Dojo version.
3. If the coach views that your coach will use do not exist, create them. For
information, see Developing reusable coach views.
4. In the human service diagram, add the coach to the diagram and then doubleclick it to edit it.
5. Drag coach views or variables onto the layout of the coach. These coach views
can be the coach views that you created earlier or the stock controls. The
variables are business objects and their parameters that are defined for the
human service . For the variables, the Designer puts the coach view that is
associated with the business object or parameter type onto the layout. For
example, if you drop a variable that is of the String type, the Designer puts a text
stock control that is bound to the variable. If the variable type does not have an
associated coach view, the Designer puts a placeholder message on the layout
614
instead. You can then use the placeholder to manually specify the binding
between the variable and a coach view. For examples of dragging a coach view
and variables onto a coach, see Example: creating a tabbed coach.Tip: For
elements in the coach that you do not plan to reuse, you can drop the
appropriate palette component onto the coach. For example, for text instructions
for the user, you can drop an HTML element and add the text as HTML code.
You can also drag fields within a variable directly onto the coach.
6. To lay out the coach views in the coach, use sections. For example, if you want
two coach views beside each other, drop them into a horizontal section. You can
embed sections within other sections.
7. To edit the coach view instances, select them and then change their properties.
For example, for text fields and buttons, change the label to something useful for
users. Many coach views contain configuration options that you can set for each
instance. You can also override the styling of the coach view instances by
adding CSS classes and attributes as HTML properties. These CSS classes are
defined elsewhere such as in the coach view definition as inline CSS or in a
CSS file uploaded as an included script.
8. If the coach views support having different types of visibility, define their visibility.
For information, see Setting the visibility of coach views.Important: You can set
the visibility of the controls in the Coaches toolkit. Custom coach views might not
provide you with this functionality. If a custom coach view does not support
setting visibility, contact the developer of the coach view to add support for this
functionality.
9. Wire the coach into the service flow by connecting boundary events that the
coach views fire to the appropriate elements in the service flow.
10. If needed, validate the data in the coach. For information about validating
coaches in client-sided human services, see Validating client-side coaches using
client-side validation and Validating client-side coaches using server-side
validation. For information about validating coaches in heritage human services,
see Validating coaches in heritage human services.
11. In the Designer or the Inspector, click .
12. Review the coach and update the coach or the coach views that it contains until
the coach looks and behaves as you intend.
616
validation service:
The following steps describe how to validate by using a server script. For
information about using a validation service to validate coach data, see Example:
validating a coach in a heritage human service.
Procedure
1. To validate the coach data before a particular boundary event occurs, select the
line for that boundary event. In the properties for the line, set the Fire Validation
property to Before. The coach has a validate icon to indicate that you can now
connect the coach to the validation script.
2. Add a server script to validate the data to the human service diagram.
3. Select the script of the validation pattern. In the Script properties, add JavaScript
code that identifies problematic data. Use the
tw.system.addCoachValidationError(CoachValidation coachValidation,
String errorBOPath, String errorMessage) API to add the error data to the
coachValidation system variable. For example, you want two fields to have a
value. They are bound to var1 and var2. To ensure that they have a value, use
(tw.local.var1 == ""){
618
Procedure
1. In the library, click the plus sign next to User Interface and select Coach View
from the list of components.
2. In the window that opens, type the name of the new coach view. Unless you are
basing the new coach view on a template, start with a blank coach view.
Restriction: The name of the coach view must be a valid JavaScript ID with the
following exceptions: it can have spaces and it cannot have underscores. That is,
you can use names like My Coach View or MyCoachView, but you cannot use
names like My_Coach_View or default; default is a reserved word in JavaScript.
For information about JavaScript IDs, see Annotated ECMAScript 5.1.
After you click Finish, the editor opens the new coach view.
3. On the Overview page, provide information about the coach view. For information
about adding tags, documentation, and icon images, see Providing information
about coach views
4. On the Behavior page, define the behavior for the coach view. For information
about adding behavior to your coach view, see Defining coach view behavior.
5. On the Variables page, define the variables that the coach view uses. For
information about defining the data used by the coach view and defining how
users can customize it, see Adding variables to coach views.
6. Define what the coach view displays to users in the Layout page: For information
about adding coach views and other palette and library items to the coach view,
619
620
621
Procedure
Provide information such as tags, documentation, and icon images for the coach
view in its Overview page:
- Add one or more tags to the coach view.Process Designer uses these tags to
categorize the coach view on the palette and within the library. If you do not specify
a tag, you can find your coach view in the No Tags category.
- In the Documentation field, provide information about the coach view that helps
people who reuse your view in their own coaches or coach views. For example,
describe the boundary events that your view fires.
- If you want your coach view to use named boundary events to move to the next
step in the service flow, select Can Fire Boundary Event. In a human service
diagram, you see these boundary events as wires. This diagram also shows the
control that fires the boundary event.
- If you want your view to be selectable as a template when someone creates a
coach view, select Use as a Template.Tip: Add a content box to your coach view
so that coach views that are based on the template have an area in which users
can drop content.
- If you want coaches or coach views that contain your coach view to display a label
at design time, select Supports a label. To have the coach view access the label
value in the runtime environment, add the following code as inline JavaScript in the
Behavior page of the coach view: this.context.options._metadata.label.get("value");
Also, see Example: showing the label of a complex coach view for information on
how to display the label at runtime.
- If you want to improve performance for the coach view, select Prototype-level
event handlers. Selecting this option means that the event handlers for the coach
view are in the prototype and not in every instance. The performance gain comes
from having one set of the event handlers per coach view definition instead of
having a set per coach view instance. However, the JavaScript code that you use
to create and access variables differs between coach view instance-level event
handlers and prototype-level handlers. For prototype-level event handlers, you
must use the this keyword. The following table shows the coding difference for
the two levels of event handlers:
Instance-level event handlers
Prototype-level event handlers
Define the variable in the inline Define the variable in the inline
JavaScript of the coach view:var JavaScript of the coach
myVariable = "123";
view:this.myVariable = "123";
Access the variable in the load Access the variable in the load
event handler:if(myvariable == "123") { event handler:if(this.myvariable ==
...
}
"123") {
...
}
You can also look at the stock controls for examples of the coding difference. The
622
stock controls of the Coaches toolkit in version 8.5.0 and higher have prototypelevel event handlers. The stock controls in earlier versions of the Coaches toolkit
have instance-level event handlers.
- If you are using the Process Designer web editor, you can specify HTML and
JavaScript to create and enhance the design-time appearance of your coach view.
For information, see Configuring the design-time appearance of coach views.
Parent topic:Developing reusable coach views
Related information:
Defining the contents of coach views
Configuring the design-time appearance of coach views
Defining coach view behavior
Adding variables to coach views
623
Procedure
Define the functionality and appearance of the coach view in its Behavior page:
- Add existing script and style sheet files from the library by using included scripts.
Typically, these files are reusable .js and .css files. You can add these files to
the library as individual web files or package them in a .zip file and add that file as
a web file. Packaging the files in a .zip file means that they maintain their relative
relationships. For example, if you package a .css file and include the images that
it refers to using relative links, the system finds the images. However, the system
does not find the images if you package a .css file in one .zip file and package
the images that it refers to in a different .zip file. If you add .css files as individual
web files, you can edit them in Process Designer. You cannot edit .css files that
are packaged in a .zip file in Process Designer. Instead, you must edit them
externally, repackage them, and then replace the .zip web file with your updated
.zip file.
- Add local custom styles to the coach view by using inline CSS. If you are pointing
to an image file in a .zip file, use the following format for the URL: file.zip!path/
file.extension.Note: The '!' notation to reference a file inside an archive is
supported only in inline CSS behavior.
If you are working in the web editor, the coach view styles specified in .css files
and inline CSS are applied to the coach view in the Layout tab, allowing you to
see how the coach view will appear at run time without having to run or test your
coach view. There are a few restrictions on this design-time styling support:
- If you use media query statements in your CSS, only media queries with a media
type screen are parsed and only the max-width and min-width specifications
are applied at design time. This design-time styling only supports simple syntax,
for example, the following media type statements are processed at design time:
@media screen .
@media all
@media (min-width: 520 px )
However, the following statements are not processed at design time: @media
not screen
- If you are using Internet Explorer 9, design-time styling is only applied for the first
25 coach views or human services that are opened. Subsequent coach views or
coaches within human services will not have design-time styling applied.
- Imports within included scripts and inline CSS will only be processed to one level
of embedding. For example, if you have inline CSS that includes the statement
@import url('File1.css'), then the css within File1 is reflected at design
time, but any import statements inside File1 are not reflected at design time.
If you have large or complex coaches and coach views, the design-time application
624
of styles might cause some performance issues. To disable design-time styling for
the current session, go to the Layout tab, right-click anywhere on the canvas and
select Disable design-time styling. For the rest of the session, the specified
coach view styles are not applied. To turn design-styling back on for the session,
right-click on the canvas and select Enable design-time styling.
- Add conditional styling to handle differences between browsers and media types.
The conditional styling overrides the default styles when the condition applies. For
example, you can apply one .css file for Microsoft Internet Explorer and a different
.css file for other browsers. You use conditional styling to apply the appropriate file.
To add conditional styling:
1. Add screen size-specific styling or browser-specific styling to a .css file. For
example, you can add styles for tablets to use a smaller font for labels and
reduce padding.
2. Add the .css file as an included script.
3. In the IE Condition or Media fields, add the condition that applies the styles in
the .css file. For example, if the .css file contains styles for a tablet
presentation, add a condition like screen and (max-width: 600px) to the
Media field. If the user's screen is 600 pixels or less in width, the coach view
uses the styles in the .css file instead of default values.
You can also add conditional styling by adding inline JavaScript and inline CSS.
Note: Any inline JavaScript styling and any styling conditions entered in the IE
Condition and Media fields are only processed at run time and are not reflected at
design time.
- Add custom Dojo build layers to improve the performance of the coach view. For
information, see Improving the performance of coach views with Dojo build layers.
- Define common variables and functions for the event handlers of the coach view
by using inline JavaScript. For information about accessing parts of the DOM, see
Accessing a child coach view by using a control ID. The editor contains a code
snippet. The editor does not show validation messages for code snippets.
- If your coach view requires modules that are written in the AMD style, register the
aliases for the dependent modules by using AMD dependencies. Script functions
can then use these aliases to refer to the modules. For information about
registering AMD modules, see Adding custom AMD modules. For an example of
using dependent modules, see Example: creating a Select control using custom
HTML.
- To insert code like <meta> tags into the header of the coach view, use Header
HTML.
- If necessary, define the functions that the coach view uses in the appropriate event
handlers. For more information, see Event handlers for the view object and the
load event handler code in Example: creating a Dojo button control and Example:
creating a jQuery button control. If you selected Can Fire a Boundary Event in the
Overview page, add code to fire the boundary events. To fire the event, code the
JavaScript to call this.context.trigger(callback) at the appropriate time.
- Improving coach view performance
To improve the performance of a coach view, you can add custom Dojo build
layers to it.
625
626
Procedure
1. If you have custom code, transform it into a Dojo build layer. For information
about Dojo build layers and how to create them by using a transform, see The
Dojo Build System.
2. Prepare your custom JavaScript:
A. Package your Dojo build layer in a .zip file, such as myLayer.zip.
B. Upload that .zip file as a managed web file.
3. On the Behavior page of the coach view, add a specific comment block at the
beginning of the inline JavaScript. The comment block consists of two sets of tag
blocks:
- @dojoConfigUpdateStart and @dojoConfigUpdateEnd contain normal
JavaScript code that updates the global dojoConfig variable before the system
loads the Dojo AMD loader.
- @layerRequiredStart and @layerRequiredEnd contain a JSON structure with
two optional properties (debug and non-debug). Each property is a JavaScript
array type that contains the full name of the layers for each mode. The full name
is the package name and the layer file name.
Tip: If you have multiple coach views that are adding the same layers, copy the
comment block into these coach views. If the layer content is the same, Process
Designer combines it so that the generated page contains only one copy of the
layer code.
The following example shows the comment block for adding Dojo build layers.
For your implementation, replace the name and location values in the Dojo
configuration section and replace the names in the layer section./* 1
@dojoConfigUpdateStart
if (dojoConfig.isDebug) {
627
dojoConfig.packages.push({
name: 'com.mycompany.dashboards',
location: com_ibm_bpm_coach.getManagedAssetUrl('myLayer_debug.zip',
com_ibm_bpm_coach.assetType_WEB, 'SYSD') + "/com/mycompany/dashboards"
});
} else {
dojoConfig.packages.push({
name: 'com.mycompany.dashboards',
location: com_ibm_bpm_coach.getManagedAssetUrl('myLayer.zip',
com_ibm_bpm_coach.assetType_WEB, 'SYSD') + "/com/mycompany/dashboards"
});
}
@dojoConfigUpdateEnd
@layerRequiredStart
{
"nonDebug":["com.mycompany.dashboards/dashboards",
"com.mycompany.dashboards/dashboardsMore"],
"debug":["com.mycompany.dashboards/dashboardsDebug"]
}
@layerRequiredEnd
* /
- 1 Using a comment prevents the comments contents from being run as actual
inline JavaScript of the coach view.
- 2 The start of the Dojo configuration section
- 3 The namespace for the package
- 4 The location of the managed file that contains the package
- 5 The start of the layer section
- 6 The name of the package and module within that package for the layer to use
in this mode. In this example, the non-debug mode loads two layers and the
debug mode loads one layer.
For more examples of how to add layers, see many of the coach views in the
Dashboards toolkit.
Parent topic:Defining coach view behavior
628
Procedure
1. Prepare your AMD package:
A. Package your AMD modules in a .zip file such as myPackage.zip.
B. Upload that .zip file as a managed web file.
C. Create a JavaScript file to define the package map for your AMD modules. For
example, create the myPackageMap.js file and add the following package map
code for AMD modules that are called myModule and myOtherModule:require({
packages: [
{name: 'myModule', location: com_ibm_bpm_coach.getManagedAssetUrl('myPackage.zip',
com_ibm_bpm_coach.assetType_WEB, 'PROJECT') + "/path/to/myModule"}
{name: 'myModule', location: com_ibm_bpm_coach.getManagedAssetUrl('myPackage.zip',
com_ibm_bpm_coach.assetType_WEB, 'PROJECT') + "/path/to/myOtherModule" }
]
});
The PROJECT parameter contains the acronym or short name of the process
application or toolkit that contains the .zip file. If the module is in the current
process application, the PROJECT parameter is optional. If the module is in a
referenced toolkit, you must include the PROJECT parameter to ensure that
the coach view can use module in the context of the process application. If the
class for the AMD module is at the root of the managed web file, do not include
the /path/to/myModule parameter. The /path/to/myModule is the path in the
.zip file to the AMD module class.
D. On the Behavior page of your coach view, add the JavaScript file as an
included script.
2. Register each AMD module in your coach view:
A. On the Behaviorr page of the coach view, select AMD dependencies.
B. Click Add and then specify the following information:
- In the Module ID column, declare the dependency on the AMD module by
using a path like myPackage/path/to/myModule.
- In the Alias column, type the alias that you use in the code to refer to the
module.
3. In your coach view code, use the alias to access the functions of the AMD
module.
Parent topic:Defining coach view behavior
629
Related information:
Developing reusable coach views
Example: creating a Dojo button control
630
Procedure
To use a control ID in your code:
1. Determine the control ID:
A. Open the service that contains the coach that you want to work with, and then
click the Coaches tab.
B. In the design area, select the control that you want to access at run time.
C. In the properties area, select General. The control ID field contains the unique
ID for the control.
2. In the Behavior page of the coach view editor, add JavaScript code:
A. Get the control ID by using the this.context.getSubview(subViewId,
requiredOrder) method. The method returns an array of nested view
instance objects. If the result does not contain a set of repeatable objects,
specify the first index of the returned array list, for example
this.context.getSubview("myCheckbox")[0]. If you need the array in the
same order as your document order, set the second optional parameter to true.
By default, it is set to false.
- subViewID
- The id parameter of the <div></div> tag of the nested view instance
object
- requiredOrder
- A Boolean value. If set to true, the method returns the array of view
instance objects in the same order as the document tree. The default is
false.
B. Enter your code to interact with the nested view instance as appropriate. See
the following example for details.
Example
631
The following example has a coach view that uses a Check Box stock control. The
check box is a subview of a parent content box view. At run time, the html rendered
is shown in the following code snippet:<div id="div_2_1" class="ContentBox" data-view-managed=false>
<div id="div_2_1_1" class="Checkbox CoachView" datatype="com.ibm.bpm.coach.Snapshot_fc633c7d_3b4f_44db_82c1_cfc7ac8b5647.Checkbox" data-binding="" data-config="config2"
data-viewid="myCheckbox" data-eventId="" >
The following code checks to ensure that the check box is selected (set to true). If
not, the user is prompted to check the check box before proceeding.if
(this.context.getSubview("myCheckbox")[0].context.binding.get("value") == true) {
return true;
}else{
alert( "Check the checkbox");
return false;
}
632
Procedure
- Specify an image file to use as a palette icon for your coach view.
- If the coach view has a UI that is a result of HTML or JavaScript code and not
other coach views, specify a layout image to display on the canvas at design time.
- If you want to bind the coach view to a managed asset at design time, select Use
URL binding. For example, the image controls use this setting so that they display
the image that they are bound to in the Process Designer canvas.
- If your coach view supports a label, then you can set the position of the label on
the canvas by specifying the Preview Label Position. Typically, you use the
center label position for UI elements like buttons.
1. If you specified a layout image and you set the preview label position to Center,
the layout image stretches to fit the label text. By default, the entire image is
stretched. However, if you are using the Process Designer desktop editor, you
can specify the parts of the image that you want to stretch in the pixel
coordinates fields. If you enter values into these fields, the image stretches only
between x1 and x2 and y1 and y2.
2. If you are using the Process Designer web editor and you have specified an
HTML snippet file or the Helper JS file (or both), any code in these files that
position the label overrides the value specified for Preview Label Position.
Procedure
633
- The simplest way to provide a design-time appearance for coach views that
accurately reflect the run time appearance is via an HTML snippet. The HTML
snippet is uploaded as a managed asset, then selected in the advanced preview
section in the coach view editor. This file should be an HTML file with a snippet
that represents the view.
1. Create an HTML snippet. This file should be an HTML file with a snippet that
represents the view. For example: <div>
<button class="DesignLabel"></button>
</div>
The HTML snippet has some features to enable content boxes and labels to be
placed appropriately.
- Class: DesignLabel
- This class is placed on the HTML element that represents the label, if the
coach view supports a label. The editor places the label string at the inner
HTML content of this element. A snippet can have multiple labels, and the
label is applied and updated to all elements.
- Class: DesignContentBox
- This class is used to indicate where a declared content box should be
located in the preview. If this class is used, then the element must also
have the data-designContentBoxID attribute defined. This attribute should
be set to the control ID of the declared content box. If multiple content
boxes are declared, each can be uniquely placed in the HTML preview. If a
content box is declared in the layout of the coach view, but there is not a div
in the HTML template with the DesignContentBox class and matching
data-designContentBoxID, then the editor will place the content box
instance at the end of the view's rendering.
Note: The Design* class names are reserved by the editor. Snippets should not
use classes matching this pattern. Similarly, the data-design* attribute names
should be avoided.
The following is an example HTML snippet: <div>
<h2 class="DesignLabel"></h2>
<div class="DesignContentBox" data-designContentBoxID="ContentBox1">
</div>
domConstruct.place(button, buttonDiv);
this.context.coachViewData.labelTextDom = document.createTextNode(labelText);
button.appendChild(this.labelTextDom);
callback();
}));
},
propertyChanged:function(propertyName, propertyValue){
if(propertyName=="@label" && this.context.coachViewData.labelTextDom){
this.context.coachViewData.labelTextDom.data = propertyValue;
}
},
};
For more information about the design-time preview APIs, see Event handlers for
coach view design-time preview.
635
Procedure
Define the variables that the coach view uses to store its association with business
data and how users can configure the coach view in its Variables page.
- To associate the coach view with data, add data such as a business object. A
coach view can have only one associated data object. A data association is not
mandatory. The coach views that this coach view contains can bind to the
associated data object or one of its parameters if it is a business object.
Restriction: To avoid errors with binding a map to an instance of the coach view,
use a list (array) of NameValuePair instead of a business data variable with the
map type. This ensures that the variable and its properties are all typed, and can
be understood by the server.
- To provide users with ways to customize coach view instances, add configuration
options. Coaches and coach views that contain your coach view display these
options as configuration properties when users select your coach view in the
layout. The users can then configure the instance by using the options that you
provided. For example, the Button stock control has the allowMultipleClicks
configuration option. If you put a Button instance into a coach view, you can see
Allow multiple clicks when you view its properties.
For service types, you must specify a default service to identify the signature of the
service.
- To provide translations for the text of your coach view, add resource bundles by
adding localization resources. For information, see Localizing user interfaces.
Parent topic:Developing reusable coach views
Related information:
Defining coach view behavior
Providing information about coach views
Defining the contents of coach views
636
Procedure
Add coach views and other palette and library items to the coach view in its Layout
page.
1. Set the type of device you are creating the layout for. For information, see
Responsive settings for coach views.
2. On the layout, drop items from the palette or from the library. These items can
include stock controls, variables, and other coach views. Use horizontal sections
and vertical sections to arrange the items.Tip: You can nest the sections. For
example, to create a two-column arrangement, drop two vertical sections in a
horizontal section. For information about dropping variables and the data binding
that occurs, see Data binding for coach views. For examples of how you can
create your own controls as coach views, see Example: creating a Dojo button
control and Example: creating a jQuery button control.
When you drop a coach view onto the layout, Process Designer automatically
selects it and shows its properties.
Remember: Consider the effect of the various browsers when you are defining
the layout and what you must do to handle their differences. For example, the
Safari browser does not have scroll bars. Without scroll bars, it might not be
obvious when, for example, table cells contain more content than their frame can
hold.
3. For each item that you dropped onto the layout page, define its properties. Each
item that you drop on the layout is a separate instance and changing its
properties does not affect the properties of other instances. For example, you
drop two instances of a Button stock control. Changing the name of one does not
affect the other. However, if you double-click a coach view instance in the layout,
the coach view opens in the editor. If you then edit the coach view, you are
changing the definition of the coach view. These changes affect all existing and
future instances of that coach view.
A. Define the general properties of the coach view instance, including setting the
following properties:
- Change its label to more appropriate text.
- Bind it to data such as a business object or one of its parameters by selecting
the data from the list. The list contains the variables that you defined in the
Variables page that have the same type as the type of the data binding that is
defined for the coach view. If the type of your selection and the type of coach
view data binding do not match, you see a warning.
- Change the view definition that it uses. If you choose to select an existing
view definition, the list contains the view definitions with a data type that
matches the type that is defined for the data binding.
For information about these properties, see Coach view general properties.
B. Configure the coach view instance by specifying or setting a value for each
option or by assigning a variable if that choice is available.To set a
configuration property to a variable, click . Click Select and then select the
637
variable from the list. The list contains the variables with a data type that
matches the type that is defined for the configuration option. Important: The
designer handles strings that are directly set in a configuration property
differently from strings that are set through a variable. If you are setting the
string by entering it directly into a configuration property, do not surround the
string with quotation marks. If you are setting the string through a variable,
surround the string with quotation marks and use escape characters where
necessary. For example, you have a Text stock control that you want to
contain only five numbers. The Text stock control has the Validation field. In
this field, you enter, as a string, the regular expression to use to evaluate the
contents of the Text stock control. If you enter the validation string, type \d{5}
. If you assign the validation to a variable, the variable is a string with a value
of "\\d{5}".
As an alternative, you can expose certain configuration properties to the coach
views or coaches that contain your coach view. For example, in your coach
view, you add a check box as a set of radio buttons and expose its True Label
and False Label configuration properties. Coaches or coach views that contain
your coach view can then set these labels to something appropriate for that
coach or coach view. Exposing the configuration property automatically
creates a configuration option as a variable in the current view. The
configuration option has data binding that matches what is defined in the
selected coach view. To expose a configuration property, click its button.
C. Set the height and width of the coach view instance and set how much padding
you want around it by setting its style properties. For information, see
Positioning options for coach view instances
D. Set how the parent coach or coach view displays the coach view instance. For
information, see Setting the visibility of coach views. For information about the
visibility values, see Coach view general properties.
E. Optional: To override existing styles on the instance, add HTML attributes and
classes to it. For information and an example of adding a class to change the
position of a text box label, see Coach view general properties.
- Adding bidirectional language support
IBM Business Process Manager can support languages that are written from
right to left and languages that are written from left to right.
- Setting the visibility of coach views
To allow or prevent users from seeing or editing a coach view, set its visibility
property.
Parent topic:Developing reusable coach views
Related information:
Adding variables to coach views
Providing information about coach views
Defining coach view behavior
638
Procedure
1. Using the steps that are contained in Setting preferences, click the Capabilities >
IBM BPM Advanced Features > Base Text Direction option.
2. In the General properties of a coach view, set the Base Text Direction property to
one of the following values:
Value
Default
Contextual
Left to Right
Right to Left
Description
Inherit the text direction that is set in the
user's profile.
Display the text according to the first
strong directional character in the string.
For example, if the first strong
directional character is from a right to
left language, display the text from right
to left. This applies to all text elements
that a Coach View displays. For
example, a Text stock control has an
Arabic label but its contents are English.
In this case, the text in the label is right
to left while the text in the field is left to
right.
Display the text from left to right no
matter what characters are in the text.
Display the text from right to left no
matter what characters are in the text.
639
What to do next
Implementing mirroring and bidirectional text for a coach or composite coach view is
an iterative activity. You might have to repeat steps 2 to 4 each of the children coach
views until you achieve the look that you want.
Parent topic:Defining the contents of coach views
640
641
For a coach view that is in the layout of a For a coach view that is in the layout of a
coach, you can set the visibility of the
coach view, you can set the visibility of
coach view according to a value, rule, or the coach view according only to a value.
script.
Procedure
In the Visibility properties of a coach view, set its visibility in one of the following
ways:
Option
Description
642
By value
643
By rule
By script
645
Procedure
1. Open a coach view and then specify a Service type configuration option in the
variable declarations.
A. In the Variables tab, click the plus sign next to Configuration Options. The
Data section opens.
B. Select the Service type option, select the default service, and then provide a
name to represent this configuration option service.Note: The default service
can optionally be overridden with a compatible service by users of this coach
view.
2. Implement the Ajax service. An Ajax service can be invoked by a simple
JavaScript call syntax or by a REST API.In the Behavior tab under Event
Handlers, select a method (load, unload, view, change, or collaboration) and
then provide code for calling the Ajax service. Use the following guidelines for
your event handler code.
- Invoking the service using a JavaScript call syntax:
- Use: this.context.options.<service_option_name>(args)Table 1.
Optional properties for args JavaScript object
Property
params
Description
(String or Object) A JSON string that
represents the input to the service. If
an object is provided, it will be
serialized into JSON format using
JSON.stringify(). As such, the
object must be JSON serializable.
(function) A callback function when
the service call returns successfully.
The callback function has a single
parameter containing the output(s) of
the service call.
load
646
error
Note: The service is invoked only using JSON input and output.
- Invoking the service using a REST API:
- Use: this.context.options.<service_option_name>.url (This contains the
URL of the Ajax service.)
- Serialize your input data in JSON format and add it to the URL using params
as the parameter name.
- Invoke the URL using an XHR call and specify the following properties
appropriately: handleAs, headers, sync, load, error properties.
Restriction: If the Ajax service uses an error end event with error code and
error data, the content of the modeled error in the Ajax service is not available in
either the JavaScript error property or in the REST API error property. The error
message returned contains the error code but no error data.
Example
The following example is JavaScript code for a load event handler:var
_this = this;
Tip: If the Ajax service output is a complex-type business object, the data object that
you get from the response contains a property holding the metadata of your object,
for example: {"status":"200","data":{"serviceStatus":"end","key":"@54","step":"End","data":
{"bookPlacedPosition":{"Floor":1,"Room":"101","Row":2,"@metadata":
{"dirty":true,"shared":false,"rootVersionContextID":"2064.c30905ba-8d17-41f4b2a8-08cbb6516ff0T","className":"PlacedPosition"}}},"actions":null}}
If you directly set the response object to your binding like the following example, the
@metadata object is added in your structure:
this.context.binding.get("value").set("BookPlacedPosition",data.bookPlacedPosition);
647
When you trigger the boundary event to the server, the server throws an exception
because it does not expect the boundary event to have the @metadata object. To
avoid an exception, remove the @metadata object from the response before you set
it to the binding, for example:delete data.bookPlacedPosition['@metadata'];
_this.context.binding.get("value").set("BookPlacedPosition",data.bookPlacedPosition);
648
Procedure
1. Use the following syntax:
- syntax
- com_ibm_bpm_coach.getManagedAssetUrl = function(assetName,
assetType, projectShortName, returnWithoutAssetName)
- returns
- the URL of the managed asset. If assetType is not one of the three allowed
(see the following table), the function returns null.
2. Use the following parameters:
Parameter
assetName (String)
assetType (String)
Description
The file name of the managed
asset.Note: You can use the '!'
notation to reference a file
inside an archive. For example,
if you are pointing to an image
file in a .zip file, use the
following format for the URL:
file.zip!path/file.extension.
The type of the managed asset.
Must be one of the following:
com_ibm_bpm_coach.assetTyp
e_WEB: web managed asset
(css, png, ..)
com_ibm_bpm_coach.assetTyp
e_SERVER: server managed
asset (for example zip, jar)
com_ibm_bpm_coach.assetTyp
e_DESIGN: design managed
asset (xsl)
649
projectShortName (String)
returnWithoutAssetName
(Boolean)
650
Procedure
To generate a unique ID:
- Open the coach view
- Switch to the Layout page
- Create a custom HTML control.
- Enter custom HTML code, and use $$viewDOMID$$ in the id attribute: <div
id="$$viewDOMID$$_myId1">
<span id="$$viewDOMID$$_myId2"></span>
<input id="$$viewDOMID$$_myId3" type="button" class="Jquerybutton" name="jbtnName" value="default"></input>
</div>
Tip: To avoid potential conflicts, use a meaningful suffix after $$viewDOMID$$, for
example $$viewDOMID$$_buttonDiv.
651
Internet Explorer 11
1. Open the Developer tools from the tool bar or by pressing F12 and go to the
Debugger tool.
2. In the Inspector, click Step Over to move to the coach that you want to test,
then click Step Into begin debugging the coach.
3. The Internet Explorer Debugger tool stops at a debugger statement at the
beginning of the coach initialization. You can see the generated page for the
coach.
4. Locate the coach view lifecycle method code and set breakpoints as required.
5. Continue normal JavaScript debugging in the Internet Explorer Debugger tool.
Google Chrome
1. Open the Google Chrome Developer tools.
2. In the Inspector, click Step Over to move to the coach that you want to test,
then click Step Into begin debugging the coach.
652
Mozilla Firefox
1. Open the Firefox Debugger.
2. In the Inspector, click Step Over to move to the coach that you want to test,
then click Step Into begin debugging the coach.
3. The Firefox Debugger tool stops at a debugger statement at the beginning of the
coach initialization. You can see the generated page for the coach. Note: You
might encounter an issue where Firefox Debugger does not display the generated
page for your coach. If this occurs, click Click to resume in the Firefox Debugger
tab, then right-click on the playback window and select This Frame > Reload
Frame to reload the coach iFrame.
4. Locate the coach view lifecycle method code and set breakpoints as required.
5. Continue normal JavaScript debugging in the Firefox Debugger tool.
653
Internet Explorer 11
1. Login to Process Portal.
2. Open the Developer tools from the tool bar or by pressing F12 and go to the
Debugger tool.
3. In Process Portal, launch the client-side human service or BPD that contains the
coach view that you want to test.
4. The Internet Explorer Debugger tool stops at a debugger statement at the
beginning of the coach initialization. You can see the generated page for the
coach.
5. Locate the coach view lifecycle method code and set breakpoints as required.
6. Continue normal JavaScript debugging in the Internet Explorer Debugger tool.
Google Chrome
1. Login to Process Portal.
2. Open the Google Chrome Developer tools.
3. In Process Portal, launch the client-side human service or BPD that contains the
coach view that you want to test.
4. The Google Chrome Debugger tool stops at a debugger statement at the
beginning of the coach initialization. You can see the generated page for the
coach. Note: You might encounter an issue where Chrome Debugger does not
display the generated page for the first coach in a client-side human service. If
654
this occurs, click Resume script execution in the Chrome debugger Sources
tab, wait until the coach is loaded, and then close and re-open the browser
debugger. Next, re-launch the client-side human service or the task in the BPD
from Process Portal. This causes the Chrome debugger to refresh and properly
display the generated page for the first coach.
5. Locate the coach view lifecycle method code and set breakpoints as required.
6. Continue normal JavaScript debugging in the Chrome Debugger tool.
Mozilla Firefox
1. Login to Process Portal.
2. Open the Firefox Debugger.
3. In Process Portal, launch the client-side human service or BPD that contains the
coach view that you want to test.
4. The Firefox Debugger tool stops at a debugger statement at the beginning of the
coach initialization. You can see the generated page for the coach. Note: You
might encounter an issue where Firefox Debugger does not display the generated
page for your coach. If this occurs, click Click to resume in the Debugger tab,
then right-click on the coach and select This Frame > Reload Frame to reload
the coach iFrame.
5. Locate the coach view lifecycle method code and set breakpoints as required.
6. Continue normal JavaScript debugging in the Firefox Debugger tool.
655
Procedure
1. Open the administrative console and click Resources > Resource Environment
> Resource Environment Provider
2. On the Resource environment providers page, click Mashups_ConfigService.
3. Under Additional Properties, click Custom properties. The list of custom
properties opens.
4. Click isDebug, change the Value field to true, and then click OK.
5. Save your changes to the master configuration.
6. Restart the application server instance.
Results
You can see the uncompressed and readable Dojo and Coach framework
JavaScript in your browser debugger.
Parent topic:Creating user interfaces for business processes
Related information:
Building coaches
Developing reusable coach views
656
657
Icon
Width
640 pixels or less
641 - 1024 pixels
More than 1024
pixels
When you build your coach or coach view, you can configure the responsive
settings for all the coach view instances in your coach or coach view by using one
screen size. You can then configure the same settings using different values for
another screen size. At run time, the pixel count of the viewport width determines
which screen-size setting the device browser uses to display the coach and the
coach views that it contains. Typically, the device browser uses the same screensize setting regardless of the device orientation. If a device has an unusual size,
however, the browser could have one screen size for the portrait orientation and a
different screen size for the landscape orientation, depending on the widths of the
two orientations.
Note that the viewport pixel counts for a web browser on a device do not
necessarily match the advertised pixel counts of the device screen. The web
browser viewport is often smaller. Websites such as http://viewportsizes.com are
useful for determining the viewport size for a particular device.
The large screen size is the default. If you do not provide different values for a
responsive setting that is available for a coach view instance, all three screen sizes
use the same value for the setting and the coach view instance appears the same in
all user environments. For example, if you set values for the coach view instance
margins for the large screen size, and do not provide values for the medium or small
screen sizes, then the large screen values apply in all user environments.
If you set the responsive settings for a coach view instance for the medium screen
size, but do not provide values for the small screen size, the medium screen size
values apply in small screen size environments.
658
659
660
This code defines the text that goes in the header division and opens the main
content division.
C. Drop a content box below the custom HTML item for the content area. The
content box is a placeholder for content that is defined by coach views and
coaches that users create based on the My Template coach view. In this case,
content placed in the content box fits between the header and footer in the My
Template coach view.
661
D. In the Layout page of the coach view, drop a custom HTML item onto the
layout canvas below the content box.
E. In the properties of the second custom HTML item, add the following HTML
code as text that goes in the footer.</div>
<div id="footer">
<h2 id="footer_text"> My Company</h2>
</div>
This code closes the content division and defines the text that goes in the
footer division.
The layout of the My Template coach view looks like the following screen
capture:
4. In the Behavior page, define the look of the My Template coach view by adding
the following code as inline CSS:#header {
text-align: center;
padding: 10px 0 10px 0;
height: 60px;
background-image: url('banner.gif');
background-repeat: no-repeat;
background-size: 100% 100%;
}
#header_text {
color:black;
border:none;
font-size:40px;
}
#footer {
padding: 5px 25px 5px 5px;
text-align: right;
background: #EAD6D1;
}
#footer_text {
color:black;
border:none;
font-size:12px;
}
#content {
background: #F8F8F8;
662
padding: 20px;
}
If the image has been packaged in a .zip file, use the following format for the
URL:url('zip_name.zip!path/banner.gif');
Tip: You can also put the CSS code in a .css file and then use Included Scripts
to refer to the file. If you use this approach, put your .css file and any images it
refers to in a .zip file. Then add the .zip file as a web file. Putting all of the files
in the .zip file means that the system can find the referenced image files.
5. To make the My Template coach view into a template, in the Overview page
select Use as a Template.
6. To represent the My Template coach view on the palette and in the New Coach
View wizard, add a palette icon. Tip: Take a screen capture of the My Template
coach view in a browser, save it as a .png file, and use that file as the palette
icon.
7. Save the My Template coach view.
When you create a coach view or coach, you can now base it on the My Template
coach view. The new coach view or coach now has the header and footer. It also
has an area between the two where you can drop content.
Parent topic:Coach and coach view examples
663
- If you have a quoteApprovers variable and use a client-side human service, use
this code in a client-side script before returning to the coach:if(!tw.local.quoteApprovers)
tw.local.quoteApprovers = {};
}
664
it Submit Supplier.
- If you use a client-side human service, select the coach that was generated
for you and name it Submit Supplier.
B. In the Coaches tab, select the coach and drag a vertical section onto the
canvas.
C. From the palette (under No Tags), drag the Supplier Information view onto the
canvas. The view properties open.
D. For the Binding, select the supplier input variable (created in step 1).
E. From the palette, drag the Button control into the vertical section and name it
Supplier Lookup.
F. Select the OK button that was previously generated and name it Submit.
3. Configure the Supplier Lookup script and sequence flow. If you use a heritage
human service, the Supplier Lookup script is a server script. If you use a clientside human service, the Supplier Lookup script is a client-side script.
A. In the Diagram tab, drag a Script component onto the canvas and name it
Supplier Lookup.
B. In the Implementation properties, provide a script for the supplier lookup
feature that is similar to the following example:if (tw.local.supplier.ID == "1234") {
tw.local.supplier.Name = "John's Restaurant";
tw.local.supplier.address = "1 anyStreet, anyCity, anyState";
} else if (tw.local.supplier.ID == "2345") {
tw.local.supplier.Name = "Jane's Bakery";
tw.local.supplier.address = "2 anyStreet, anyCity, anyState";
}
C. In the diagram, connect the Start Event component to the Submit Supplier
coach. Then connect the Submit Supplier coach to the Supplier Lookup script.
Finally connect the script back to the Submit Supplier coach to create a loop.
D. Select the line going from the Submit Supplier coach to the Supplier Lookup
script. The line properties open.
E. For the End State Binding, click Select and then select the Supplier Lookup
button (created in step 3).
F. Connect the Submit Customer coach to the End Event component and then
select the connecting line. The line properties open.
G. For the End State Binding, click Select and then select the Submit button
(created in step 2).
4. Save changes, and then run the service. A separate web browser window opens
showing your coach.
5. Test the features in your application.
A. In the ID field, type either 1234 or 2345 and then click Supplier Lookup. The
corresponding supplier name and address data is returned.
B. To end the process, click Submit. The human service is complete.
Example artifacts
Create the artifacts listed in the following tables before you begin the example.Tip:
For properties that are not specified, accept the default settings.
Table 1. Business data objects
Name
Parameters
665
Supplier
Contents
Script component with added
script for the lookup feature,
similar to:tw.local.results = new
tw.object.listOf.String();
Packages.java.lang.System.out.println("tw.local
.text: " + tw.local.text);
Packages.java.lang.System.out.flush();
if (tw.local.text.charAt(0) == '1') {
tw.local.results[0] = "1234";
} else if (tw.local.text.charAt(0) == '2') {
tw.local.results[0] = "2345";
} else {/*
*/
}
Contents
Text controls: Supplier ID,
Name, and AddressSupplier ID
propertiesBinding:
Supplier.IDEnable
Autocompletion:
OnAutocompletion Service:
Supplier ID Lookup (Ajax
service)Name
properties:Binding:
Supplier.NameAddress
properties: Binding:
Supplier.Address
Properties
Configure the human service
using the steps in this example.
666
The second page contains a set of phone numbers. You use a coach view to add
the fields to the page.
The third page contains a table of addresses. In this case, the coach view you add
667
Note:To perform this task, you must be in the IBM Process Designer desktop
editor.
1. Create the Customer business object. Customer has id(String),
firstName(String), and lastName(String) parameters. It also has two
complex parameters: phoneNumbers(PhoneNumber) and addresses(Address).
- PhoneNumber is a business object that has home(String), work(String), and
cell(String) parameters.
- Address is a business object that has number(String), street(String), and
city(String) parameters.
With the Customer business object, addresses is an array of the Address type,
so ensure that you select Is List for it.
For information about creating business objects, see Creating custom business
objects in Process Designer.
2. Create the coach view for the PhoneNumber business object:
A. Create the PhoneNumberView coach view.
B. In its Variables page, add the PhoneNumber business object as the business
data variable named phoneNumber.
C. In the Layout page, drag the home, work, and cell parameter variables onto
the layout. A text control is added to the layout for each variable because it is
668
6. In the Coaches page, drag a tabs stock control onto the Customer coach layout.
The tabs control is in the Section category of the palette.
669
The id, firstName, and lastName variables are parameters of the Customer
variable.
8. Create the Phone Numbers page:
A. Drag the PhoneNumberView coach view onto the tab control. If you did not
add a tag to the coach view, you can find it in the NoTags category on the
palette. You can see a PhoneNumberView 1 tab in the tab control.
B. Bind the PhoneNumberView coach view to the customer.phoneNumber
variable. This action means that any data users enter into the fields gets set
in the variable for the heritage human service.
C. Select the tab.
D. In the General properties, change the label of the PhoneNumberView instance
to Phone Numbers.
670
D. In the Configuration properties, select Show Add Button and Show Delete
Button. By doing this step, you can add and subtract address rows when you
run the heritage human service later in this example.
10. Add a button control below the tab section and relabel it to OK, The button
broadcasts a boundary event and you can use it to wire the coach in the
heritage human service flow.
671
11. In the diagram, connect the start node to the Customer coach and then connect
the Customer coach to the end node.
672
button.
673
modules.
B. In the Behavior tab under Event Handlers, select load and then provide a
custom script. For this example, you can use the following script:var selectElement
this.context.element.getElementsByTagName("select")[0];
Description
The load event has the context
of payload data as well as that
of the business data object
associated with it (added in
step 2).
connect.connect(selectEle The onChangeHandle variable
ment, "onchange"
in the script has the new value
selected in the Select control.
The onChange event of the
custom HTML control is called
using
connect.connect.Tip:connec
t.connect(selectElement,
"onchange" is derived from
ement, "onchange".
this.context.binding.get(
"value").set("TSAPP_Accou
ntType",
newValue.target.value);
4. To test your work using a human service, create a heritage human service and
then do the following:
A. On the Diagrams tab, add a coach.
B. On the Variables tab, add TSAPP_ValidateDocumentCaseProperties as input,
output, and private variable types.
C. On the Coaches tab, select the coach, drag the getAccountTypes coach view
onto the canvas, and then select the
674
Reference
Table 2. Example business objects
Library item
Business Objects
Example name
TSAPP_ValidateDocumentCase
PropertiesParameters:
TSAPP_Zipcode (String)
TSAPP_Age (String)
TSAPP_AccountStatus (String)
TSAPP_CustomerType (String)
TSAPP_Name (String)
TSAPP_City (String)
TSAPP_AccountType (String)
In the coach view,
TSAPP_ValidateDocumentCase
Properties variable type is bound
to caseProperites.
675
Procedure
1. Add custom HTML code to a coach view:
A. In the Layout page, drag the Custom HTML Advanced item onto the canvas.
B. In the HTML properties, select the Text option and then provide your custom
HTML code. For this example, you can use the following code to define a
button control:<input type="button" class="dojobutton" name="dbtnName" value="default"></input>
2. Configure the load event handler with a custom script:
A. Register the Dojo button module and alias that the coach view will load
dynamically.
1. In the Behavior tab, select AMD dependencies.
2. Click Add and then specify the following information:
- In the Module ID column, type dijit/form/Button. This declares a
dependency on dijit button module.
- In the Alias column, type Button. This is the alias name used in the code
to refer to the dijit button.
B. Under Event Handlers, select load and then provide the custom script. For
this example, you can use the following script:var buttonNode =
this.context.element.querySelector("input");
var _this = this;
Description
this.context.options._met Retrieves the label value from
adata.label.get("value") the configuration options.
676
Results
The custom button will be available in the palette.
677
Procedure
1. Add custom HTML code to a coach view:
A. In the Layout page, drag the Custom HTML Advanced item onto the canvas.
B. In the HTML properties, select the Text option and then provide your custom
HTML code. For this example, you can use the following code to define a
jQuery button:<input type="button" class="Jquerybutton" name="jbtnName" value="default"></input>
2. Upload a compressed (.zip) file that contains the jQuery library assets and style
sheets and then select the individual files to include:
A. From the list of library assets, click the plus sign next to Files and select
Server File from the list of components.
B. Select your compressed jQuery library assets file (jQuery.zip for this example)
and then click Finish.
C. After the upload is complete, go to the Behavior tab of the coach view and
click the plus sign next to Included Scripts.
D. In the list of server files, click the twistie next to jQuery.zip to view the contents
of the uploaded file.
E. Select a file to include. Each file to include is selected individually. The .css
files are included in a specific order. For this example, the following files are
included in the order that they are listed:
- jquery-1.4.js
- jquery-ui-1.8.custom.min.js
- core.css
- jquery-ui-1.8.custom.css
3. Under Event Handlers, select load and then provide the custom script. For this
example, you can use the following script:var _this = this;
$('.Jquerybutton', this.context.element).button(
{label: this.context.options._metadata.label.get("value")}).bind('click', function() {
_this.context.trigger(function() { console.log("jQuery button boundary event handled");})
});
Description
this.context.options._meta Retrieves the label value from
data.label.get("value")
the configuration options.
678
this.context.trigger(...)
4. Save changes.
Results
The custom button will be available in the palette.
679
Procedure
1. Create the client-side human service that will contain the coach to be validated.
See Building a client-side human service.
2. In the Variables tab for the human service, create two private variables,
startDate and endDate, and set the type of each variable to Date.
3. In the client-side human service diagram, rename the coach to Prompt for
4. In the Coaches tab, from the Variables section of the palette, drop the
startDate and endDate parameters onto the coach. Leave the default OK
680
5. In the coach, select the Start date parameter and ensure that it is bound to the
startDate variable in the Behavior section of the General tab.
6. Repeat step 5 for the End date parameter to verify that it is correctly bound to
the endDate variable, and then save the coach configuration.
7. In the diagram, add a script, an exclusive gateway, and an intermediate event,
which automatically becomes a stay on page event. Rename the script to
Validate variable values and the exclusive gateway to Validation
errors?. Connect these elements in the following order:
A. Delete the flow line between the coach and the end event.
B. Connect the coach to the script.
C. Connect the script to the exclusive gateway.
D. Connect the exclusive gateway to the stay on page event. Rename the flow
line to Yes. Because this is the first flow line leaving the gateway, it has the /
indicator to show that it is the default flow. The stay-on-page event loops the
flow back to the coach.
E. Connect the exclusive gateway to the end event.
The human service flow now contains a coach validation pattern. The flow goes
first to the script. If the data is not valid, the script creates and adds validation
errors to the tw.system.coachValidation object. The gateway determines the
path that the flow takes. If the data is valid, the flow goes to the next step in the
flow, which is the end event. If the data is not valid, a validation error is recorded
and the flow loops back to the coach.
8. Select the validate variable values script and, in the Script tab, enter the
following JavaScript construct:if (tw.local.startDate.getTime() > tw.local.endDate.getTime())
tw.system.coachValidation.addValidationError("tw.local.startDate", "The start date must precede the end date. Set
the start date before the end date, and try again.");
In the coachValidation object, the first string contains the full variable path to
the elements whose data is to be validated. The second string is the message
681
for the user, which specifies what is wrong with the data and tells the user how
to fix the problem. Note:
- If the data element that is being validated is not bound to a coach view, there is
nowhere to display a validation error if one occurs.
- If a coach view that is being validated contains rich text, the validation script
must remove the formatting before validating the contents.
- If you are validating a list and you want the error to refer to the entire list, the
variableName parameter must include [] as a suffix. This matches coach view
binding where [] indicates that the object is a list. For example, if a coach view
is bound to tw.local.var3[], which is a list, you need code like the following
example: tw.system.coachValidation.addValidationError("tw.local.var3[]", "Var3 has validation error");
9. Select the exclusive gateway and, in its Implementation properties, create the
test. The test is tw.system.coachValidation.validationErrors.length==0
. The test checks for the presence of validation errors and, if there are none,
routes it to the rest of the flow. If there are errors, the flow goes to the stay on
page event so that the coach can show the control with the problematic data and
a message.
10. Save your changes, and then run the human service by clicking Run .
11. In the browser that displays the coach, test the validation by completing the
following steps:
A. Set the End date to a date that precedes the start date. Click OK. The
browser highlights the Start date field and displays a warning icon. If you
hover over the warning icon, you see a message that the start date must
precede the end date.
B. Set the End date to a date that succeeds the start date. Click OK. The
human service completes successfully because both dates are valid.
Parent topic:Coach and coach view examples
Related information:
Validating client-side coaches using client-side validation
Example: validating a coach in a heritage human service
682
4. In the diagram, add the Create Application coach, and then open the coach.
5. From the Variables section of the palette, drop the name, salary, and
creditLimit parameters onto the coach. Relabel the default OK button to
Submit.
683
6. In the diagram, connect the Credit Application coach to the start and end nodes.
7. Select the connection between the Credit Application coach and the end node.
Set Fire Validation to Before. The connection now has a check mark at its start.
The coach has an icon to indicate that you can now connect the coach to the
validation service. This change means that when the user clicks the Submit
button, the flow first goes to the validation service to do the data validation. If the
data is valid, the flow then goes to the end node. If you leave Fire Validation at
its default of Never, the data validation does not occur and the flow goes directly
to the end node.
8. Create the service to validate the coach data:
A. From the library, create a general system service called
CreditApplicationFormValidation.
B. On the Variables page of the service, add
application(CreditCardApplication) as an input of the service.
Important: The name and the type of the service input must match the name
and type of the coach variable that contains the data that you want to
validate.
Add validate(CoachValidation) as an output of the service. The service
must have one output only and it is of the CoachValidation type. The
presence of this output indicates that the service is a validation service. In this
case, the example uses the input to provide the data that the service
validates.
C. Add a server script to the service diagram and connect the start and end
nodes to the script.
684
D. In the implementation of the server script, add the following code to construct
the CoachValidation business object:tw.local.validate = new tw.object.CoachValidation();
if (tw.local.application.name == ""){
tw.system.addCoachValidationError(tw.local.validate, "tw.local.application.name",
"The name cannot be empty.");
}
if ( tw.local.application.salary <= 0){
tw.system.addCoachValidationError(tw.local.validate, "tw.local.application.salary",
"The salary must be above 0.");
}
if (tw.local.application.creditLimit > 2 * tw.local.application.salary){
tw.system.addCoachValidationError(tw.local.validate, "tw.local.application.creditLimit",
"The credit limit cannot be more than double the salary. " + "The maximum credit limit is $" +
2 * tw.local.application.salary + ".");
}
when they hover over an indicator. If the data is valid, the system processes the
boundary event to move to the next step.
14. Save your changes and then run the heritage human service by clicking the
button.
15. In the browser that displays the coach, test the validation by doing the following:
A. Leave the Name field empty, type a 1 into the Salary field and into the
Credit Limit field. Click Submit. The browser displays a message that the
Name field cannot be empty.
B. Type a name into the Name field, and replace the 1 in the Salary field with a
0. Click Submit. The browser displays a message that the salary must be
more than 0.
C. Replace the 0 in the Salary field with a 1. Replace the 1 in the Credit Limit
field with a 3. Click Submit. The browser displays a message that the credit
limit cannot be more than twice the salary.
D. Replace the 3 in the Credit Limit field with a 2. Click Submit. The human
service now finishes because all three values are now valid.
Restriction:Pay attention to the following behavior when you debug a coach and
step through each activity in the flow as the coach service is running: If coach data
validation is required at a step, the validate boundary event path loops back and
goes back to open a new coach. Because the validate boundary event response
cannot go back to the originating coach during the debugging, you do not see a
visual error during debugging. You can step through a coach and see the validation
error on the debug page, but the flow always returns to a new coach.
After you have debugged the validation path, and you have reviewed the debug info
page, including tw.system.coachValidation error information, select one of the
following options:
- Run to continue.
- Run to the next break point that is defined in the next step in a regular boundary
event flow. This option moves to the next step in the regular boundary event flow.
686
Procedure
1. Create the heritage human service, the coach that calls an Ajax service, and the
Ajax service.
A. Beside User Interface, click + and select Heritage Human Service. Name the
service Display Supplier Parts.
B. Drag a Coach from the palette to the left side of the canvas. Name the coach
Get Supplier Name. Drag a Server Script to the right of Get Supplier Name
. Name the server script List Supplier Parts. Drag another Coach to the
right of List Supplier Parts. Name the Coach Show Parts from Supplier.
Save your work.
C. Double-click Get Supplier Name. The coach editor opens. Drag a Text field to
the canvas. Select the text field and in the Properties view select the General
tab. Change the Label field to Enter Supplier: Q for QuickServ or P
for ProServ. Select the text field and in the Properties view select the
Configuration tab. Select Enable Autocompletion. Beside Autocompletion
Service, click New. The New Ajax Service window opens. Enter the name
Get Supplier Name for the name of your Ajax service and click Finish.
Click Variables. Note that the expected input and output variable names (text
and results) and their types have already been created for you.
Click Diagram. Drag a Server Script from the palette to the canvas and name
it Get Supplier Name. Select Get Supplier Name and click the
Implementation tab in the Properties view. Add the following JavaScript. This
code will select the QuickServ supplier name when Q is entered by a user and
select the ProServ supplier name when P is entered.
tw.local.results = new Array();
if(tw.local.text=="Q"){
tw.local.results[0]=("QuickServ");
}
else if(tw.local.text=="P"){
tw.local.results[0]=("ProServ");
687
Conect the Start node to Get Supplier Name and Get Supplier Name to End
. Save your work. Close the Ajax editor.
Back in the Get Supplier Name coach, drag a Button beneath the text field.
Rename it Next. Save your work. Click Diagram.
2. Create a server script that lists the supplier data.
A. Double-click List Supplier Parts. In the Properties view, click the
Implementation tab and add the following JavaScript:tw.local.product = new
tw.object.listOf.ProductLine();
switch (tw.local.supplier) {
case "QuickServ":
tw.local.product[0] = new tw.object.ProductLine();
tw.local.product[0].sku = "Z34RT1GF";
tw.local.product[0].description = "Window Sill";
tw.local.product[0].price = "$35.40";
tw.local.product[1] = new tw.object.ProductLine();
tw.local.product[1].sku = "YT76UJ8F";
tw.local.product[1].description = "Glass Pane";
tw.local.product[1].price = "$37.50";
break;
case "ProServ":
tw.local.product[0] = new tw.object.ProductLine();
tw.local.product[0].sku = "Z34RT1GF";
tw.local.product[0].description = "Door Latch";
tw.local.product[0].price = "$20.39";
tw.local.product[1] = new tw.object.ProductLine();
tw.local.product[1].sku = "YT76UJ8F";
tw.local.product[1].description = "Door Bell Chimes";
tw.local.product[1].price = "$67.50";
}
Click Variables and Add Private to create a variable for this data. Use private
variables for data that should be hidden. Name the variable product. Click Is
List as the variable will provide a list of items. Click New to define a business
object that will contain the product data. Enter ProductLine for the business
object name. When the Business Object editor opens, click Add in the
Parameters section and add three variables: sku, description and price.
Leave the type as a String. Save your work. Close the Business Object editor.
Click Add Input to add a variable for the user's input which will determine the
supplier, that is, a Q for QuickServ or a P for ProServ. Name the input
supplier and leave the type as String. Save your work.
Click Coaches. Select Get Supplier Name and select the Text field. In the
Properties view, select General. Beside Binding, click Select and choose
supplier from the menu. Save your work. The binding in this case associates
the input variable in the Human service with the text element. Save your work.
688
689
- For the tablet, the inspector can see the Findings part of the coach and the
buttons. The Inspection part of the coach is no longer visible.
- For a smartphone, the inspector can see the amount of space between the check
boxes reduce so that they occupy less space:
690
B. In the configuration properties, enable Automatic Wrap. Repeat this step for
the other section. By setting this property, if there is not enough room to
display all of the controls side-by-side, the section moves some of them below
the others instead of displaying scroll bars.
C. Select the horizontal section that contains the check boxes. In its configuration
options, enable Show Border.
D. To remove the bold from the check box labels, select a check box. In the
HTML attributes, add the following class: notBold. Repeat this step for the
F. Save the coach view. If you look at the coach view in the Layout page, the
labels for the check boxes are no longer in bold font.
3. Create the Inspection CV coach view
A. Click the
for User Interface and then select Coach View.
B. For the name, enter Inspection CV.
C. In the Variables page, add the following configuration options:
- inspector(String)
- inspectionDate(Date)
When you create the configuration options, ensure that you set their type to
692
Report.
D.
E.
F.
G.
controls.
Rename the OK button to Cancel and rename the other two buttons to Save
and Submit Report.
In the Configuration properties of the section, enable Automatic Wrap.
Rename the two vertical sections in the first horizontal section to Findings
and Inspection.
In the first vertical section, add the Findings CV coach view. In the second
vertical section, add the Inspection CV coach view.
I. Select the Inspection section. In its Visibility properties, set Visibility to Read
only. The information in this part of the report would come from the system so
making it read only means that the user cannot change it.
J. For the Findings section, open its configuration properties and select the
Show Border property. Repeat this step for the Inspection section.
K. Hide the title bars of the two horizontal sections by selecting them and, in their
general properties, set their Label visibility to Hide.
L. Save the human service.
M. Run the Inspection human service. The web browser opens and displays the
coach.
6. Add more space between the Building and Area inspected controls. The elements
in the Findings coach view must also align with each other.
A. Open the Findings CV coach view and select the Building control.
B. In the positioning properties, set the margins to 0px 20px 0px 0px. In the
Margin field, the first number is for the top margin, the second number for the
right margin, the third number is for the bottom margin, and the fourth number
is for the left margin.
Alternatively, you can click the icon beside the Margin field. In the window
that opens, type 20px in the Right field and 0px in the other fields. Click OK.
Tip: Notice that the Building control and the Area inspected control are no
694
longer vertically aligned. If the controls are nested within multiple sections as
the Building and Area inspected controls are in this example, Process
Designer inserts .5em as a margin around these controls. When you set a
value for the margin, you override this value and this change can cause some
controls to move out of alignment. You can compensate for this situation in a
number of ways:
- Add .5em to the top margin of the Building control.
- Set the margins of the Area inspected control to 0px, which sets all of its
margins to 0 pixels. This is the approach chosen in this example.
C. Change the margin of the Area inspected control to 0px.
7. Move the Findings output text control, the section that contains the check boxes,
and Comments control to the right so that they align with the Building control:
A. Select the Findings control and set its Margin positioning property to 0px 0px
0px 18px.
B. Select the horizontal section control that contains the check box controls and
set its Padding positioning property to 0px 0px 0px 16px. Set its Width
positioning property to 100%. Without the width setting, the section shifts to the
right and this shift can lead to scroll bars for browsers that support them or it
can lead to truncating 16 pixels. Setting the width to 100% limits the width to
the container or viewport width.
C. For each check box control, set its Margin positioning property to 0px 20px
5px 0px. The five pixels added to the bottom margin helps even the space to
the border above and below the check boxes. The Findings label and the
border of the check box section now align with the Building control.
D. Select the Comments control and set its Margin positioning property to 10px
0px 0px 16px.
E. Save your changes.
F. Open the human service and then run it. In the coach, all of the controls in the
coach view align at run time.
This step completes the appearance of the coach when users view it using
desktop monitors or notebook computers.
695
696
3. Open My Coach and add My Complex CV to it. The following table shows My
Complex CV within a coach at design time and at run time. In both cases, you
cannot see the label for the view:
My Complex CV in a coach in
697
C. Save the view. If you open My Coach in the human service, you can now see
the label for My Complex CV.
Using the label of the output text to display the coach view name means that,
at runtime, the name is styled as a label. If you instead set the binding to
display the coach view, at runtime, the name is styled as normal text.
D. Save the view.
6. Test that you have bound the coach view label:
A. Open My Human Service and open My Coach.
B. Change the label of My Complex CV to My Complex CV Label. Save the view.
699
C. Run the human service. My Complex CV now shows the label that you give it in
My Coach. The following table shows My Complex CV at design time and at
run time.
My Complex CV in a coach in
700
701
Procedure
1. To start developing the mockup, change the title of the Heritage Coach by
clicking the IBM Business Process Manager Heritage Coach title bar in the
design area.
2. In the Heritage Coach option of the properties, type Initiate New Case Enter Customer Information.
3. Drag a Two-Column section from the palette onto the design area so that it is
positioned directly below the existing Section Title.
4. Drag four Text controls from the palette onto the design area so that two Text
controls are in each column side by side.
5. Click the Section Title in the design area and in the properties type Customer
Information in the Title text box.
6. Change the text labels for the fields. Click an Input Text control in the design
area and in the properties, change the Label for each control to match the
following list:
- Name:
- Phone:
- Email:
- Physical address:
7. Right-click the default Checkbox control, and from the pop-up menu that opens,
select Delete. Do the same for the default Input Text control. Neither of these
controls is needed for this sample Coach.
8. Drag a One-Column with Title section from the palette onto the design area so
that it is positioned directly below the existing Customer Information section.
9. While the new section is still selected, type Case Information in the Title text
box in the properties.
10. Drag a Text control from the palette onto the design area and place it in the new
Case Information section.
702
11. While the new Text control is still selected, type Case Type in the Label text box
under the Common section. Then choose Single Select from the Control Type
field under the Behavior section.
12. Select the Presentation option in the properties and in the Manual Data section,
click the Add button.
13. Add values and display text. In the Manual Data section, use the Add button to
add the values and display text shown in Table 1.Table 1. Values and display
text to add under the Manual Data section
Value
billing
defect
tracking
Display text
Billing
Product defect
Late Shipment
14. Drag a Date Selector component from the palette onto the design area and
place it directly below the drop-down control in the new Case Information
section.
15. In the properties for the Date Selector component, change the label to Date
Received .
16. Click the default Button Group at the bottom of the design area, click the
Presentation option in the properties, and change the label for the OK button to
Submit.Important: The action associated with any given button applies only to
the fields and other controls in the same section as the button.
17. Save your work.
18. Click the Preview tab to see how the Heritage Coach will look when the service
runs. You can make adjustments as you see fit in the Design tab.Lets change
this scenario slightly. In this version a service gets input data at run time which is
used to populate the values of the drop-down list. Since these values are only
known at run time, the values will not appear when you press the Preview tab at
development time. These values will appear in the user interface at run time.
- Setting column widths in a Heritage Coach
Learn how to change the column width for each section of a Heritage Coach.
- Setting the number of columns in a Heritage Coach
Learn how to set the number of columns for each section of a Heritage Coach.
Parent topic:Building Heritage Coaches
Related information:
Configuring heritage coach controls
703
Procedure
1. Open the service that contains the Heritage Coach that you want to change and
then click the Coaches tab.
2. In the design area, click the section that contain the columns you want to set.
3. Click the Presentation option in the properties. If you selected a section
containing more than one column, each column is listed in the Columns area in
numeric order based on the column ID. Click one of the columns listed to enable
the Column Width text box.
4. Specify the width of the column in the Column Width field using any valid HTML
size attribute such as 50% or 110px.
5. Click the Preview tab to see how the Heritage Coach layout will look when the
service runs.
Parent topic:Adding sections to a Heritage Coach and controlling the layout
Related information:
Setting the number of columns in a heritage coach
704
Procedure
1. Open the service that contains the Heritage Coach that you want to change and
then click the Coaches tab.
2. In the design area, click the section that you want to change.
3. Click the Section option in the properties and then click the up and down arrows
for the # of Columns option to increase or decrease the number of columns in
the section. In the following example, one additional column is added to a section
that contains a nested two-column section. Notice the behavior of the nested
section when its parent section is configured.
4. Click the Preview tab to see how the Heritage Coach layout will look when the
service runs.
Parent topic:Adding sections to a Heritage Coach and controlling the layout
705
706
707
Procedure
1. Create a heritage human service as described in Building a heritage human
service and name it according to what the service performs.
2. Open the diagram for the new human service and drag the integration service
from the library to the diagram. When you have an existing service that you want
to nest in another service, you can drag the existing service directly from the
library to the diagram of the parent service. This creates the Nested Service
component with the service attached in a single step.
3. If not already selected, click the nested service in the diagram to view its
properties.
4. Because you already created the input and output variables for the nested
service, the Data Mapping tab for the parent service includes those variables.
5. From the Input Mapping section, click the auto-map icon. The Create variables for
auto-mapping dialog box opens, indicating that a matching private variable was
not found in the parent service, and should be created.
6. Select the suggested variable item and then click OK. A private variable of that
name is created for the parent Service and automatically mapped to the input
variable of the nested service, making it available to all components in the parent
service.
7. From the Output Mapping section, perform the automapping step to create the
matching private variable to capture the output from the nested service. You can
see the private variables added for the parent service.
8. Click Save in the main toolbar.
Parent topic:Example: building an integration service with a Heritage Coach
708
Procedure
1. Click the Diagram tab for your service and then drag a Heritage Coach
component from the palette to the diagram. Place the Heritage Coach
component before the nested service component.
2. While the Heritage Coach component is selected in the diagram, click the Step
option in the properties and type a name for your coach in the Name field.
3. Click the Coaches tab.
4. Drag the variable that you declared for your integration service from the palette
to the Heritage Coach. An input text field is created with a mapping to the
variable, and a label that matches the variable.
5. In the Heritage Coach, select the group containing the default OK button, and
then in the properties, click the Presentation option.
6. In the Buttons section, click OK definition and type Search in the Label text box.
7. Click the Preview tab for the Heritage Coach to see your label change.
8. Click Save in the main toolbar.
9. Click the Diagram tab for your service.
10. Drag another Heritage Coach from the palette to the diagram and name it View
search results . Place the Heritage Coach component after the nested service
component.
11. Click the Coaches tab.
12. From the palette, drag an Output Text control to the Heritage Coach.
13. In the properties, select the Output Text option in the properties and in the
Behavior section, click the Select button to create a binding to the results
variable.
14. From the list that opens, find and select the appropriate output variable.
15. Click the Diagram tab to return to the diagram view of your service. Select the
Sequence Flow tool from the palette and then connect the components.
16. Click Save in the main toolbar.
17. To test your service, click the Run icon in the upper right corner. The Heritage
Coach opens in your browser.
Parent topic:Example: building an integration service with a Heritage Coach
709
Procedure
1. Starting with the Expense Reimbursement BPD, right-click the Enter Expenses
activity and select Activity Wizard from the list of options.
2. In Activity Wizard - Setup Activity, make the following selections:Table 1.
Recommended selections in Activity Wizard - Setup Activity
Option
Activity Type
Selection
User Task
710
Service Selection
3. Type a name for the new service in the Name field. (The name for this sample
service is Enter Expense.)
4. In Activity Wizard - Setup Activity, click the Next button.
5. In Activity Wizard - Parameters, choose the existing process variables to use
as input and output for this new service.
A. You can see the private variable named request. For this sample, set Input
to false and leave Output set to true. This enables you to collect the data for
the expense using this new service and then output those values for the
subsequent process steps to act upon.
B. Click the Finish button. The new service is created and attached to the
activity. The new service includes a single Coach.
6. Double-click the activity for which you created the new heritage human service
using the Activity Wizard. The new service opens in the Designer.
7. Click the Coaches tab and then click the listed coach component. Because you
used the Activity Wizard, the coach includes a form element for each of the
parameters in the request structure. The coach designer is where you
customize the coach layout and create or edit the bindings between inputs and
outputs. Notice that when the coach designer is open, the palette shows all the
elements (sections and controls) that you can use in a coach. (Hover over a
control to view a brief description. See Building heritage coaches for more
information about the coach designer.)The items in the palette are described in
the links at the bottom of this page.
8. In the coach designer, right-click the Status control and select Delete from the
list of options. The status of a request is not data that we need to collect from
employees, but is a value set later after a request is further processed and so it
can be removed.
9. Click the Id control. In the properties, the Id: field label matches the parameter
in the request variable. Change the label to Employee ID: so that employees
know exactly which ID to provide.
10. Click the Type control. In the properties, the Type: field label matches the
parameter in the request variable. Change the label to Employee type:.
11. To enable employees to select from an existing list of employee types, in the
properties for Employee type, click the drop-down list for Control Type and
choose Single Select.
A. Select Presentation in the properties. Under Widget Style, select Drop
Down List for Widget Type.
B. Under Manual Data, click Add to add a value and associated display text for
each option that you want in the drop-down list.
12. To add a Cancel button to the coach, select the control that contains OK in the
coach designer.
A. In the Presentation properties, go to the Buttons section and click Add.
B. In the Button Details, enter Cancel for the label and click Is Cancel.
13. Click Save in the main toolbar.
14. Click the Preview tab at the bottom of the coach designer to view the coach.
The Preview tab shows how the coach will appear to users when the BPD runs.
711
15. Click Run Service in the upper right corner to view the coach in a web browser.
Parent topic:Examples of building services with heritage coaches
712
Procedure
1. Starting with the Expense Reimbursement BPD, right-click the Enter Expenses
activity and select Activity Wizard from the list of options.
2. In Activity Wizard - Setup Activity, make the following selections:
- Under Activity Type Selection, select User Task.
- Under Library Element Selection, select Create a new heritage human
service.
3. Type a name for the new heritage human service in the Name field. (The name
for this sample service is Enter Expense.)
4. In Activity Wizard - Setup Activity, click the Next button.
5. In Activity Wizard - Parameters, choose the existing process variables to use
as input and output for this new service.
A. You can see the private variable named request. For this sample, set Input
to false and leave Output set to true. This enables you to collect the data for
the expense using this new service and then output those values for the
subsequent process steps to act upon.
B. Click Finish. The new heritage human service is created and attached to the
activity. The new service includes a single coach.
713
6. Double-click the activity for which you created the new heritage human service.
The new heritage human service opens in the heritage human service editor in
the Designer view.
7. Click the Coaches tab and then click the listed coach component. Because you
used the Activity wizard, the coach includes a form element for each of the
parameters in the request structure. The coach designer is where you
customize the coach layout and create or edit the bindings between inputs and
outputs. Notice that when the coach designer is open, the Palette view shows all
the elements (sections and controls) that you can use in a coach. Hover over a
control to view a brief description. For more information about the coach
designer, see Building heritage coaches.The items in the palette are described
in the links at the bottom of this page.
8. In the coach designer, right-click the Status control (input text field) and select
Delete from the list of options. The status of a request is not data that is
collected from employees, but is a value set later after a request is further
processed and so it can be removed.
9. Click Id (input text field). In the properties, you can see the label for the field is
Id: to match the parameter in the request variable. Change the label to
Employee ID so that employees know exactly which ID to provide.
10. Click the Type control (input text field). In the properties, you can see the label
for the field is Type to match the parameter in the request variable. Change the
label to Employee type.
11. To enable employees to select from an existing list of employee types, in the
properties for Employee type, from the Control Type list choose Single Select.
A. Select the Presentation option in the properties. Under Widget Style, select
Drop Down List for Widget Type.
B. Under Manual Data, click Add to add a value and associated display text for
each option that you want in the drop-down list.
12. To add a Cancel button to the coach, select the control that contains OK in the
coach designer.
A. In the Presentation properties for the control, go to the Buttons section and
click Add.
B. In the Button Details field, enter Cancel for the label and click Is Cancel.
13. Click Save in the main toolbar.
14. Click the Preview tab at the bottom of the coach designer to view the coach.
The Preview tab shows how the coach appears to users when the BPD runs.
You can also click Run Service in the upper right to view the coach in a web
browser.
Parent topic:Examples of building services with heritage coaches
714
Procedure
The first part of this procedure takes you through the steps of creating an Ajax
service. Subsequent steps describe how to associate this service with a coach in
order to populate fields in a user interface or form.
1. In the left hand navigation, hover over the Implementation category, and click the
plus (+) sign. Select Ajax Service.
2. Name your new service. For example, if you were building a form for users to look
up product information based on a supplier name, you might have a service called
"Query Product Line".
3. With the new service open in the diagram editor, drag a Server Script component
from the palette, and use sequence lines to connect the script to the Start and
End Events.
4. Declare the variables to pass into and out of your service in the Variables tab.
For example if you were planning to use the service to accept the name of a
supplier, and return a set of product information, you might create an input
variable called "Supplier" of type string and an output variable called
"ProductInfo". Because the product information is complex, you can create a new
business object called "ProductLine" which contains fields for product SKU,
description, and price. For more information on how to create variables see
Declaring and passing variables and Creating custom business objects in
Process Designer.Tip: For this example, because you are expecting multiple
products to be returned, be sure to enable the Is List check box for the
ProductInfo output variable. Also For the Supplier variable, ensure that the
Has Default check box is enabled.
5. Click the Diagram tab and then click the Server Script component in the diagram.
6. In the Implementation properties, enter the script for the Ajax service to run. In the
example described above, you might have the following script using the specified
variables sku , description , and price for two different suppliers: QuickServ
and ProServ.tw.local.ProductInfo=new tw.object.listOf.ProductLine();
switch(tw.local.Supplier)
{
case "QuickServ":
tw.local.ProductInfo[0] = new tw.object.ProductLine();
tw.local.ProductInfo[0].sku = "Z34RT1GF";
tw.local.ProductInfo[0].description = "PowerServ 1500";
tw.local.ProductInfo[0].price = 3540;
tw.local.ProductInfo[1] = new tw.object.ProductLine();
715
tw.local.ProductInfo[1].sku = "YT76UJ8F";
tw.local.ProductInfo[1].description = "PowerServ 1735";
tw.local.ProductInfo[1].price = 3750;
break;
case "ProServ":
tw.local.ProductInfo[0] = new tw.object.ProductLine();
tw.local.ProductInfo[0].sku = "Z34RT1GF";
tw.local.ProductInfo[0].description = "Reliant DW";
tw.local.ProductInfo[0].price = 2039;
tw.local.ProductInfo[1] = new tw.object.ProductLine();
tw.local.ProductInfo[1].sku = "YT76UJ8F";
tw.local.ProductInfo[1].description = "Reliant X1";
tw.local.ProductInfo[1].price = 6750;
}
716
717
Procedure
1. Open the service that contains the Heritage Coach that you want to work with and
then click the Coaches tab.
2. Drag a combo box control from the palette onto the design area.
3. Click the Presentation option in the properties.
4. Under Manual Data, click the Add button to create a row for each option that you
want to add to the list. The value that you type in the Display Text column is the
name of the option that is displayed to the user at run time.
5. Click the Preview tab to see how the list will work when the service runs.
Parent topic:Configuring Heritage Coach controls
Related information:
Populating a list with dynamic data in a heritage coach
718
See...
Declaring and passing variables
The following procedure and
Building a heritage human
service for an example
Building an Integration service
for an example
Procedure
1. Open the service that contains the Heritage Coach that you want to work with and
then click the Coaches tab. Open or create a service for which you have declared
a variable that is a complex structure.
2. Drag a Combo Box control from the palette onto the design area.
3. While the Combo Box control is still selected, click the Presentation option in the
properties.
4. Under Manual Data, click Add to include static instructions at the top of the dropdown list. For this example, the static text is: -- Select Dept 5. Under Dynamic Data, for the Based On option, click List Variable.
6. For the Dynamic Binding option, click Select to choose the preexisting variable
from the library. For this example, the control must be bound to a complex
structure that is a list.
7. Click the Preview tab to see how the list works when the service runs. A service
inputs data at run time which is used to populate the values of the drop-down list.
Because these values are only known at run time, the values do not appear when
you select the Preview tab at development time. These values do appear in the
user interface at run time.
719
720
Procedure
1. To display the values of the parameters in the requisition variable in a Heritage
Coach, click the Coaches tab.
2. Drag the input requisition variable from the palette to the design area.
3. Right-click and select Delete for the parameters that should not be displayed as
output text; select all remaining fields and change the Control Type to Output
Text.
4. Click the Section option in the properties and increase the number of columns to
2.
5. Click the Preview tab to see how the table will look when the service runs. When
you run the tutorial BPD, the Heritage Coach displays the table with the
appropriate data for the manager to act upon.
Parent topic:Configuring Heritage Coach controls
Related information:
Populating a table control using an SQL query in a heritage coach
721
722
Procedure
1. Open the service that contains the Heritage Coach that you want to work with and
then click the Coaches tab.
2. Drag a Table control from the palette onto the design area.
3. While the Table control is selected, click the Presentation option in the properties.
4. Click the Execute SQL check box to enable it.
5. In the Data Source text box, type the data source from where you want to
retrieve the data. By default, the data source is "jdbc/TeamworksDB" , which
points to IBM BPM databases. When you want to use a data source other than
the jdbc/TeamworksDB data source, ensure that it is an XA data source. If you
use a non-XA data source, or an emulated XA data source, you might receive an
error about a database connection failure.
6. In the SQL text box, enter an SQL query to select the data that you want from the
data source. For example, you could select the ID, status, and employee type
from a table named R2H_PositionType by entering the following text:select id, status,
employeeType from R2H_PositionType
723
The order of the entries is in the order which the table rows are returned. Use an
ORDER BY clause in your SQL statement to override this behavior.
Parent topic:Configuring Heritage Coach controls
724
Procedure
1. Open the service that contains the Heritage Coach that you want to work with and
then click the Coaches tab.
2. Drag a Custom HTML control from the palette onto the design area.
3. While the Custom HTML control is selected, click the Presentation option in the
properties.
4. In the HTML text box, type the variable whose value will populate the HTML block
at run time. In this example, tw.local.myHTMLBlock is declared in the Variables
tab for the service and then used to set the label of the HTML block at run time.
Type the following in the HTML text box: <p><#=tw.local.myHTMLBlock#><p> .
5. To render the content in the HTML block, run the service. When you run the
service, the variable is evaluated and its runtime value is then passed to the
Heritage Coach. For a quick test, define a default value for the variable from the
Variables tab. Select the variable and then, under the Default Value section,
click Has Default. When Has Default is selected and the default value is added
to the field, which is This is the default value that can be used to test
the Coach. The Heritage Coach displays the runtime content of the HTML.
Parent topic:Configuring Heritage Coach controls
Related information:
Binding a complex data structure to a Table control in a heritage coach
725
Procedure
1. Open the service that contains the Heritage Coach that you want to work with and
then click the Coaches tab.
2. Click the Heritage Coach control that you want to make a required input area.
3. Click the Visibility option in the properties. By default, input controls are visible to
and can be edited by everyone. The Visibility properties enable you to restrict
what process participants see in the runtime Heritage Coach, and under what
conditions they see it.
4. Select the Override Parent Visibility check box. Doing so allows you to change
the default Visibility properties.
5. From the Default Visibility list, select the Required (full access) for everyone
option.
6. Optional: Clear the Override Parent Visibility check box to set the Visibility
properties back to read-only mode.
7. Run the service to test the runtime Heritage Coach. If you leave the required input
text box empty and then click Next, the input text box is shown in a different color
and you are not able to end the task successfully until you supply the required
input.
Parent topic:Configuring Heritage Coach controls
Related information:
Controlling field and other formatting in heritage coaches
726
Procedure
1. Open the service that contains the Heritage Coach that you want to work with
and then click the Coaches tab.
2. Drag a List control from the palette onto the design area.
3. In the properties for the control, type Do you want to contribute? in the
Label text box.
4. Click the Presentation option in the properties.
5. Under the Manual Data section, click the Add button. With the Add button,
create three Value-Display pairs, one for each list item option as shown in the
following table:Table 1. Entries for the Value and Display Text fields
Value
true
false
defer
Display Text
Yes
No
Decide at a later date
6. Drag a Text control from the palette onto the design area.
7. In the properties for the control, type 401K Contribution % in the Label text
box.
8. Click the Visibility option in the properties.
9. Select the Override Parent Visibility check box. Doing so allows you to change
the default Visibility properties.
10. From the Default Visibility drop-down list, select the Hidden (no access) for
everyone option.
11. Click the Depends on Control button. This creates a new override condition.
12. Under the Control Dependent Visibility section, select the Required (full
access) option from the Visibility drop-down list.
13. From the Control list, specify the coach control the input value of which is to
determine if the selected control is displayed to participants when the service
runs. In this example, the control is the Do you want to contribute? List
control.
14. From the Operator list, select the ==(equals) operator.
727
15. In the Value text box, type true. This is the value that you assigned to the Yes
list option in step 5.
16. Drag a Date Selector control from the palette onto the design area.
17. In the properties for the control, type Date in the Label text box. Depending on
the selection list choice, this can be the date of contribution or the date until a
contribution decision is deferred.
18. Click Visibility, and repeat the steps above to make the Date Selector dependent
on the control Do you want to contribute?.
19. From the Operator list, select the in operator.
20. In the Value text box, type "{'true','defer'}". These are the values that you
assigned to the Yes and Decide at a later date list options in step 5. The Date
Selector will be displayed if either of these options is selected.
21. Save the Heritage Coach and then run the service to see how the Input and
Date Selector controls are hidden and then shown according to the visibility
rules you have specified.
Parent topic:Configuring Heritage Coach controls
Related information:
Displaying a control to a specific group in a heritage coach
728
Procedure
1. Open the service that contains the Heritage Coach that you want to work with and
then click the Coaches tab.
2. Click the Heritage Coach control that you want to display to only those members
of a group.
3. Click the Visibility option in the properties.
4. Click the Override Parent Visibility check box to enable it. Doing so allows you
to change the default Visibility properties.
5. From the Default Visibility drop-down list, select the Hidden (no access) for
everyone option.
6. Click the Depends on Group button. This creates a new override condition.
7. Under Group Dependent Visibility, click the Select button to choose the group
that you want.
8. Under Group Dependent Visibility, select the visibility option that you want for this
group from the Visibility drop-down list.
9. Save the Heritage Coach and then run the service to see how the control is
hidden and then shown according to the visibility rules you have specified.
Parent topic:Configuring Heritage Coach controls
729
Procedure
1. Open the service that contains the Heritage Coach to work with.
2. Click the Variables tab and add the private variables that you need for the
custom script. For this example, add Boolean variables named visible ,
enabled , and required.
3. Click the Coaches tab.
4. Click the Heritage Coach control for which you want to add visibility control.
5. Click the Visibility option in the properties.
6. Click the Override Parent Visibility check box to enable it. Doing so allows you
to change the default visibility properties.
7. From the Default Visibility list, select the Hidden (no access) for everyone
option.
8. Click the Custom Script button.
9. In the Custom Visibility section, enter the JavaScript rule to control visibility.
The following example uses a server-side JavaScript function, and so return
statements are required. For custom visibility using server-side JavaScript,
return one of the following values (must be in upper case): Table 1. Values
returned for custom visibility
Value
"NONE"
"READ"
"FULL"
"REQUIRED"
Result
Hidden
Disabled
Editable
Required
The following script causes the runtime engine to determine if user input is
required:var customVisibility;
if(tw.local.visible) {
if(tw.local.enabled) {
if(tw.local.required) {
customVisibility = "REQUIRED";
}
} else {
customVisibility = "READ";
}
} else {
customVisibility = "NONE";
730
}
return customVisibility;
If user input is not required, the control can be edited, but it is not required. If
the value of tw.local.visible is false, the control is not displayed to the user.
10. You can set default values for the variables (that you added in step 2) and then
run the service to test the script.
Parent topic:Configuring Heritage Coach controls
Related information:
Validating user input for heritage coach button controls
731
Procedure
1. Open the service that contains the Heritage Coach that you want to work with and
then click the Coaches tab.
2. In the design area, click to select the control for which you want to add a
validation script.
3. Click the Presentation option in the properties.
4. If multiple buttons are included in the control, under Buttons, click the button that
needs the validation script.
5. In the text box under the Validation Script section, type the JavaScript to
validate that the required controls have been set and contain values as expected.
To do this, use the control ID of each required control. The following example is
client-side JavaScript that uses the default controls included when you add a new
Heritage Coach to a service. The following validation script checks to ensure that
the check box is enabled (set to true). If not, the user is prompted to check it
before proceeding by clicking OK. if ( document.getElementById("checkbox0_checkbox").checked == true
){
return true;
} else {
alert( "Check the checkbox");
return false;
}
6. Save the Heritage Coach and then run the service to test the script.
What to do next
In many cases, an OK or Submit button that runs a validation script on the user
input is accompanied by a Cancel button which discards the user input. When Is
Cancel is selected for a button, clicking the button discards any changes to variable
values, and moves the token to the next step in the flow.
Parent topic:Configuring Heritage Coach controls
732
733
Procedure
1. Open the service that contains the Heritage Coach that you want to work with and
then click the Coaches tab.
2. Click the Heritage Coach control for which you want to add formatting.
3. Click the Presentation option in the properties.
4. Under Widget Style, click the Select button next to the Format field and choose
the format that you want:Table 1. Input required for the Format options
Option
Currency: $ ###,###,###.##
Currency: ###,###,###.##
Currency: ###,###,###.##
Integer: ###,###,###
Decimal: ###,###,###.##
US phone: (###) 000-0000
US SSN: 000-00-0000
Example
Enter the value 123456789 , the value is
formatted to $123,456,789
Enter the value 123456789 , the value is
formatted to 123,456,789
Enter the value 123456789 , the value is
formatted to 123,456,789
Enter the value 123456789 , the value is
formatted to 123,456,789
Enter the value 123456789 , the value is
formatted to 123,456,789
Enter the value 5555555555 , the value
is formatted to (555) 555-5555
Enter the value 123456789 , the value is
formatted to 123-45-6789
5. Save your changes. When you run the service that contains the Heritage Coach,
the values typed into the control are automatically formatted as shown in the
preceding examples. If a user enters non-numeric characters, those characters
are removed. If a user enters only non-numeric characters, no formatting is
applied.
Parent topic:Controlling field and other formatting in Heritage Coaches
Related information:
Adding custom format types in a heritage coach
Using characters to apply custom numeric formatting in a heritage coach
734
735
Results
Since no decimal placeholder is
specified, values entered into the control
during run time are rounded up to the
next integer. For example, if a user
enters the value 34.2 into the control, the
value is rounded up to 35 .
For additional decimal positions typed in
to the control during run time, decimals
less than five are rounded down, and
decimals greater than or equal to five are
rounded up. For example, the value
34.24 would be rounded down to 34.2 ,
and the value 34.57 would be rounded
up to 34.6 .
Procedure
1. Open the service that contains the Heritage Coach that you want to work with and
then click the Coaches tab.
2. Click the Heritage Coach control for which you want to add formatting.
3. Click the Presentation option in the properties.
4. Under Widget Style, type the characters that you want to use as placeholders in
the Format field. The following characters are available:
Table 2.
Characters available to use as placeholders
Character
#
Name
Digit placeholder
736
Description
A digit is copied into
output. If there is no digit
in this position, then
nothing is stored in the
output.
Zero placeholder
Padding placeholder
Decimal separator
737
Thousand separator
Percentage
738
Section separator
Other
739
740
741
Procedure
1. Open a service that includes several variables, and click the Variables tab.
2. Click the Link Localization button and select the localization resource (in this
example, Localized Formats) that you want to link to the service variables as a
resource bundle.
3. Create a Heritage Coach that includes an input text control named Time. Then
bind the formatting of the control to the localization resource bundle and
localization key by typing <#= tw.resource.LocalizedFormats.time #> into
the Format field.
4. Save your changes.
5. Optional: You can test the binding. To test the binding, change the interface
language to svenska in IBM Process Portal preferences. Then run the BPD that
contains the service and run the task from the Process Portal. When a you enter
a 6-digit value such as 182400 into the Time field, the value should be formatted
to 18.24.00 , which conforms to the formatting that you specified.
Parent topic:Controlling field and other formatting in Heritage Coaches
742
Procedure
1. Open the Process Designer desktop editor.
2. Open a Heritage Human service.
3. In the Diagram page, add or select a Heritage Coach. To add a Heritage Coach,
scroll to the bottom of the palette.
4. Open the Heritage Coach.
5. From the Controls section of the palette, drag a Date Selection control onto the
editor.
6. In the Properties view, switch to the Presentation tab.
7. Select Hebrew or Islamic in the National Calendars list.
8. Run the Coach. The Hebrew or Islamic calendar is displayed in the date
selector, instead of the Gregorian calendar.
9. You can also change a preference in Process Portal to display the Hebrew or
Islamic calendar. For more information, see Setting preferences in Process
Portal
Parent topic:Controlling field and other formatting in Heritage Coaches
743
Procedure
1. Open the service that contains the Heritage Coach that you want to work with and
then click the Coaches tab.
2. In the design area, click to select the Button Group control that you want to align.
3. Click the Presentation option in the properties.
4. Select the alignment (Left, Center, or Right) for the Button Group from the dropdown list.
5. Click the Preview tab to see how the buttons will be displayed when you run the
service.
Parent topic:Controlling field and other formatting in Heritage Coaches
Related information:
Aligning check boxes and radio buttons
Setting column widths in a heritage coach
Setting the number of columns in a heritage coach
744
Procedure
1. Open the service that contains the Heritage Coach that you want to work with and
then click the Coaches tab.
2. In the design area, click to select the Dual List control that you want to align.
3. Click the Presentation option in the properties.
4. From the Widget Type drop-down list, select Multiple Check Boxes .
5. From the Orientation drop-down list, select Vertical or Horizontal.
6. Click the Preview tab to see how the buttons will be displayed when you run the
service.
Parent topic:Controlling field and other formatting in Heritage Coaches
Related information:
Setting column widths in a heritage coach
Setting the number of columns in a heritage coach
745
746
Procedure
The following steps describe how to establish which type of documents you want to
display and upload using the Document Attachment control:
1. Open the service that contains the Heritage Coach that you want to work with,
and then click the Coaches tab.
2. Drag a Document Attachment control from the palette onto the design area.
3. While the Document Attachment control is selected, click the Document
Attachment option in the properties if not already selected.
4. In the Behavior section, select a Connection Type from the drop-down list:
- IBM BPM documents
- IBM Content Integrator
5. If you selected IBM Content Integrator for the Connection Type, complete the
following steps:
A. Click the Connection option in the properties.
B. Provide the following information: Table 1. Input required for connection
properties
Property
Description
747
Repository ID
User name
Password
What to do next
Configure the control to display and upload documents for your connection type. By
configuring the control, you can attach documents to the Heritage Coach for which
you configured the connection type.
748
749
Procedure
The following procedure describes how to display a list of IBM BPM documents in
your Heritage Coach using the Document Attachment control:
1. Open the service that contains the Heritage Coach that you want to work with and
then click the Coaches tab.
2. Drag a Document Attachment control from the palette onto the design area or
click to select an existing control.
3. While the Document Attachment control is selected, click the Presentation option
in the properties.
4. Under Display Documents, select or clear the Associated Process Instance
check box. This setting causes the control to display only those documents
uploaded in previous steps of the running process instance. The check box is
selected by default. When not selected, the control displays all documents,
regardless of instance, BPD, or process application from which they originated,
when disabled. Important: If you disable this check box, be sure to set properties
that clearly identify the documents to display. If you do not, the number of
displayed documents could be much larger than expected or than is useful.
5. If you cleared the Associated Process Instance check box, choose one of the
following options:
Option
Description
750
All Properties
E. If you want to supply a default name for all documents that the user uploads,
type the JavaScript for the default in the Default Name text box. For example,
type <#= tw.system.user_fullName #> to make the current user name the
default name for uploaded documents. If you supply a default name, but want
the user to be able to change the default, click the User Editable check box to
enable it.
F. Click the Add Properties check box to enable it if you want to add properties
to uploaded documents. Then click the Add button to add the properties that
you want. Each property should have a name and a value. For example, you
might add a property with a name of client and a value of smith. The
properties that you add to uploaded documents enhance the Display
Documents capability of the control. All properties that you add to uploaded
documents can be used to select the documents to display.
G. Save the Heritage Coach and then run the service or BPD to test your
configuration.
What to do next
To see how these controls appear to users, work with documents in the Process
Portal.
752
Procedure
The following procedure describes how to display a list of ECM documents in your
Heritage Coach using the Document Attachment control:
1. Open the service that contains the Heritage Coach that you want to work with and
then click the Coaches tab.
2. Drag a Document Attachment control from the palette onto the design area or
click to select an existing Document Attachment control.
3. While the Document Attachment control is selected, click the Presentation option
in the properties.
4. In the Item Class Name field, enter the name of the document type that you want
to retrieve from the ECM repository, and click the Add button. All properties that
exist for the document type that you specify are displayed. This enables you to
choose the properties to use to determine the documents to display.
5. Determine whether you want to remove or filter any of the listed properties:
- To remove unwanted properties, click the property name and then click the
Remove button.
- To filter for particular properties, enter a value in the Filter Value column.
Important: The filters that you specify must match the actual property values in
the ECM repository.
For example, if one of the properties for a document type is ClientIndustry ,
you could limit the results to a specific industry by entering the following text in the
Filter Value column: automotive . You can also use an *(asterisk) as a wildcard
when establishing filters. For example, enter the following text to filter for all
properties that begin with auto : auto* . Or, simply enter an asterisk to retrieve
documents for all properties: * .
6. Click All Properties or Any Properties.
- If you select All Properties, documents must match all properties that you add
753
to be displayed.
- If you select Any Properties, if documents match any one of the properties that
you specify, the control displays them.
7. In the Display table, enter the value that you want the Heritage Coach interface to
use as the label for each property, and enter a value in the Display Value column
for each property.
8. Save the Heritage Coach and then run the service or BPD to test your
configuration.
9. Choose one of the following options to configure whether users can upload
documents to the connected ECM repository using the Document Attachment
control:
- If you do not want to configure the Document Attachment control to enable
document uploads, clear the Enabled check box under Upload Documents.
- If you want to configure the Document Attachment control to enable document
uploads, complete the following steps:
A. Open the service that contains the Heritage Coach that you want to work with
and then click the Coaches tab.
B. Drag a Document Attachment control from the palette onto the design area or
click a preexisting Document Attachment control to select it.
C. While the Document Attachment control is selected, click the Presentation
option in the properties. By default, the Enabled check box under Upload
Documents is selected. This setting causes the control to display an Add
Document button. When the service runs, the user can click the Add
Document button and then use the fields provided to browse for the file that
they want to upload to the ECM repository, provide a title for the document,
and then click OK to upload the document. The user can upload multiple
documents to the connected ECM repository using the control.
D. If you want to supply a default name for all documents that the user uploads,
type the JavaScript for the default in the Default Name text box. For example,
type <#= tw.system.user_fullName #> to make the current user name the
default name for uploaded documents.
E. If you supply a default name, but want the user to be able to change the
default, click the User Editable check box to enable it.
F. Click the Add Properties check box to enable it if you want to add properties
to uploaded documents. Then click the Add button to add the properties that
you want. Each property should have a name and a value.
G. Save the Heritage Coach and then run the service or BPD to test your
configuration.
What to do next
To see how these controls appear to users, work with documents in the Process
Portal.
754
Procedure
The following procedure describes how to configure the Document Viewer Heritage
Coach control to enable users to display a document from a list and configure the
Document Viewer Heritage Coach control to display a single document:
1. Open the service that contains the Heritage Coach that you want to work with and
then click the Coaches tab.
2. Drag a Document Viewer control from the palette onto the design area or click a
preexisting Document Viewer control to select it.
3. Click the Document Viewer option in the properties.
4. For the Association field, choose Document Attachment from the drop-down list.
5. For the Control field, choose the Document Attachment control currently included
in your Heritage Coach that you want to associate with this Document Viewer
control. The Document Attachment control establishes the list of documents from
which the user can choose. When a user selects one of the documents, it is
displayed in the viewer.
6. Save the Heritage Coach and then run the service or BPD to test your
configuration. After testing the configuration, you can configure the Document
Viewer Heritage Coach control to display a single document by choosing the
connection type and then completing the configuration for the chosen connection
type.
7. Configure the Document Viewer Heritage Coach control to display a single
document by choosing the connection type:
A. Open the service that contains the Heritage Coach that you want to work with
and then click the Coaches tab.
B. Drag a Document Viewer control from the palette onto the design area or click
a preexisting Document Viewer control to select it.
C. Click the Document Viewer option in the properties.
D. For the Association field, choose None from the drop-down list.
E. Click the Presentation option in the properties.
F. Select the Connection Type from the drop-down list: IBM BPM documents,
IBM Content Integrator, or URL.
- IBM BPM documents
755
756
Value
IBM Content Integrator (ICI)
web service URL
Description
Select the environment
variable that contains the root
URL of the deployed
application (SOA web
services). See Setting
environment variables to learn
how to define an environment
variable of type ICI web
service URL.
Select the environment
variable that contains the
name of the IBM Content
Integrator connector that you
want to use to access the
ECM repository. See Setting
environment variables to learn
how to define an environment
variable of type ICI Connector
Name.
User name required to log in
to the ECM repository.
Password required to log in to
ECM repository.
Repository ID
User name
Password
C. In the Item Class Name field, enter the name of the document type that you
want to retrieve from the ECM repository, and click the Add button. All
properties that exist for the document type that you specify are displayed. This
enables you to choose the properties to use to determine the document to
display. The control displays the first document that matches the properties
that you choose.
D. To remove unwanted properties, click the property name and then click the
Remove button.
E. Optional: Limit the results by entering filterable text in the Filter Value column.
Note: The filters that you specify must match the actual property values in the
ECM repository.
For example, if one of the properties for a document type is ClientIndustry
, you could limit the results to a specific industry by entering the following text
in the Filter Value column: automotive .
F. For the First Document Matching field, click All Properties or Any Properties.
- If you select All Properties, the document must match all properties that you
add to be displayed.
- If you select Any Properties, if a document matches any one of the
properties that you specify, the control displays it.
G. Save the Heritage Coach and then run the service or BPD to test your
configuration.
- If you selected URL as the connection type for the Document Viewer control,
complete the following steps:
757
758
Procedure
To embed an IBM BPM report in a Heritage Coach:
1. Open the service that contains the Heritage Coach that you want to work with and
then click the Coaches tab.
2. Drag a Report control from the palette onto the design area.
3. While the Report control is selected, click the Presentation option in the
properties.
4. Under Report Settings, click the Select button to choose the IBM BPM report that
you want to embed. If the report does not yet exist, you can click New to create a
new report. Specific instructions for creating and configuring reports are provided
in the related information.
5. In the Page to Display field, use the drop-down list to choose the report page that
you want to display in your Heritage Coach.
6. In the Filter Parameters panel, click the Add button to choose parameters by
which to filter the report results. Provide the appropriate value in the Value
column.
7. Click the Report option in the properties. In the Common area, you can provide
documentation for the report and add a label.
8. In the Behavior area, you can provide an unique control ID for the report and
adjust the number of rows and columns that the report spans within the Coach.
9. Save the Heritage Coach and the run the service to ensure the report is displayed
properly.
Parent topic:Adding documents and reports to Heritage Coaches
759
760
XSLT
HTML
CSS
JavaScript
Description
The design of a Heritage Coach is
described in Extensible Markup
Language (XML). As you drag sections
and controls to a Heritage Coach, IBM
BPM automatically generates the XML
definition of the Heritage Coach. You can
view the XML while you're building a
Heritage Coach by clicking the Code
View icon in the toolbar.
The Extensible Stylesheet Language
Transformation (XSLT) transforms the
XML definition to the runtime HTML form.
The XLS renders a server-side-scriptlet
that is run to generate the HTML.
The client (web browser) renders the
HTML that the Heritage Coach generates
from its XML definition through XSLT
processing.
The Cascading Style Sheet
(coach_designer.css in the following
image) instructs the client how to render
the HTML output.
JavaScript provides the methods and
functions that implement runtime
Heritage Coach features, such as
dynamically adding rows to a table or
governing the visibility of Heritage Coach
controls. JavaScript that is embedded in
the XML definition of a Heritage Coach is
evaluated by the runtime engine before it
is rendered to HTML by the web browser
client. Both client-side and server-side
JavaScript is used to render Heritage
Coaches.
761
If you have the required technical expertise, you can use the following methods to
customize Heritage Coaches:
- Override and customize Cascading Style Sheets (CSS)
- Edit the XML definition
- Edit the JavaScript files
- Edit the XSL transformation rules
The following topics describe some of the customization options most commonly
used for Heritage Coaches.
Parent topic:Customizing Heritage Coaches
Related information:
Specifying a custom CSS for a heritage coach
762
763
Procedure
1. Open the service that contains the Heritage Coach that you want to work with
and then click the Coaches tab.
2. In the design area, click to select the Heritage Coach control that you want to
customize.
3. Click the Customization option in the properties.
4. Click the Add Class button.
5. Under Class Details, type a name in the Class Name text box. By default, this
field includes the name, class . You need to replace this text with the class
name that you want.
6. To override the CSS styles for the label of the Heritage Coach control, click the
Create label override button. This creates a . class_name .twLabel { } CSS
class, which is stored directly within the Heritage Coach and can be accessed as
described in the following step.
7. In the design area, click the top-level section of the Heritage Coach (named
IBM Business Process Manager Coach by default) and then click the CSS option
in the properties.
8. In the CSS text box, type your CSS override settings. For example, the
following CSS override changes the color of the label text to red and the
typeface of the label text to bold: . class_name .twLabel { color:red;
font-weight:bold; }
9. To override the CSS styles for the Heritage Coach control itself, go back to the
Customization properties for the selected control and click the Create control
override button. This creates a . class_name .twControl { } CSS class.
10. In the design area, click the top-level section of the Heritage Coach (named IBM
BPM Coach by default) and then click the CSS option in the properties.
11. In the CSS text box, type your CSS override settings. For example, the following
CSS override changes the typeface of the text in the control to italic: .
class_name .twControl { font-style:italic; }
12. Save the Heritage Coach and then run the service to test the CSS overrides.
Parent topic:Customizing Heritage Coaches
Related information:
Specifying a custom CSS for a heritage coach
764
765
Procedure
1. Add the CSS file that you want to use to your current project or to a referenced
toolkit as described in Managing external files.
2. Open the service that contains the Heritage Coach that you want to work with and
then click the Coaches tab.
3. In the design area, click the top-level section of the Heritage Coach (named IBM
Business Process Manager Coach by default) and then click the Heritage Coach
option in the properties.
4. For the CSS Override field, click the Select button and choose the CSS file that
you added in step 1. (You can click the New button and add a CSS file as
described in Managing external files.)
5. Save the Heritage Coach and then run the service to test the CSS overrides.
Parent topic:Customizing Heritage Coaches
766
Procedure
1. Add the .xsl file that you want to use to your current project or to a referenced
toolkit as described in Managing external files.
2. Open the service that contains the Heritage Coach that you want to work with and
then click the Coaches tab.
3. In the design area, click the top-level section of the Heritage Coach (named IBM
Business Process Manager Coach by default) and then click the Heritage Coach
option in the properties.
4. For the XSL Transform Override field, click the Select button and choose the
.xsl file that you added in step 1. You can click the New button and add a new .xsl
file as described in Managing external files.
5. Save the Heritage Coach and then run the service to test the XSL transform
override.
Parent topic:Customizing Heritage Coaches
767
Procedure
1. Open the service that contains the Heritage Coach that you want to work with and
then click the Coaches tab.
2. In the design area, click to select the Heritage Coach control that you want to
customize.
3. Click the Customization option in the properties.
4. Click the Add Class button.
5. Under Class Details, type a name in the Class Name text box. By default, this
field includes the name, class . You need to replace this text with the class name
that you want.
6. To override the CSS styles for the Heritage Coach control, click the Create
control override button. This creates a . class_name .twControl { } CSS class.
7. In the design area, click the top-level section of the Heritage Coach (named IBM
BPM Coach by default) and then click the CSS option in the properties.
8. In the CSS text box, type the CSS override settings to specify the maximum input
length (in pixels) for the control's input text box. For example, the following CSS
override sets the length to 110 pixels: . class_name .twControl {
width:110px; }
9. Save the Heritage Coach and then run the service to test the CSS overrides.
Parent topic:Customizing Heritage Coaches
Related information:
Making an input control a required field in a heritage coach
768
Procedure
1. Open the service that contains the Heritage Coach that you want to work with and
then click the Coaches tab.
2. In the design area, click to select the Heritage Coach section that you want to
customize.Note: This example requires a Heritage Coach section with a visible
title that is nested within another section.
3. Click the Customization option in the properties.
4. Click the Add Attribute button.
5. Type showHide in the Name text box. By default, this field includes the name,
key . You need to replace this text with the key name that you want.
6. To make the section collapsible, type true in the Value text box. By default, this
field includes the text, value . You need to replace this text with the value that
you want. Note: To make the section collapsible and collapsed by default, type
hidden in the Value text box.
7. Save the Heritage Coach and then run the service to test the custom attribute.
What to do next
The custom attributes that you add when building a Heritage Coach pass
information to the XSL about how the page should be rendered. When you switch to
the Heritage Coach XML view, you can see any name-value attributes in the XML.
IBM Business Process Manager provides the following attributes that you can use
just as the showHide attribute is used in the preceding steps:
Table 1. Available custom attributes
Attribute
cssStyle
cssClass
Description
Overrides a CSS
style
Overrides a CSS
class (be sure to
include the standard
CSS class if you
want the default
functionality as well)
Applies to
Input Text (or
equivalent)
Input Text (or
equivalent)
769
Example value
width: 100px
inputText
important
height
width
precision
symbolPre
symbolPost
position
Enables scrollable
tables and sections
(the table or section
will always be the
given height, even
when there is not
enough data to fill it.
The header of the
table scrolls with the
data.)
Sets the width of a
table column
Displays numbers
with the specified
number of digits
after the decimal
Displays the given
symbol before a
value
Displays the given
symbol after a value
Specifies the
location of a label,
such as on top (the
label must be
visible)
Table or Section
200px
Cell
75%
InputText or Output 2
Text
InputText
InputText
Label
top
You can create completely new attributes and extend the capabilities of the Coach
Designer by adding XML attributes directly to a Heritage Coach's XML. When you
add attributes to a Heritage Coach's XML, you need to customize the Heritage
Coach XSL to support the new attribute.
770
771
772
773
Procedure
1. Open Process Designer and your process application or toolkit in the Designer
view.
2. In the library, click the plus sign next to User Interface and select Localization
Resource.
3. Provide a name for your new resource bundle and click Finish.
4. Optional: If you opened the Process Designer desktop editor, you can add each
of the language locales that you will translate your user interface into by clicking
Add and selecting each locale from the list.
5. For each translatable string in your application, enter a translation key and a
default value for that key. The default value is the value that is displayed if no
translation is available.
6. After you have defined all of your translation keys, you can export the resource
bundle for translation. Click Export to export the existing set of keys to a .zip file
to which you will add the corresponding translated properties files.
7. If you are in the web editor, or if you did not perform Step 4, you need to
manually create a new properties file for each language locale that you will
translate your user interface into. For each language that you want your
application to support, create a copy of the exported properties file, renaming it
according to the language that it will be supporting. For example, if your default
properties file is my_application.properties and you want your application to
support Japanese, create a copy of the file called
my_application_ja.properties.Note: Language support also extends to
specific countries. For example, different locale options are provided for English
(en_US, en_CA), French (fr and fr_CA), and Portuguese (pt and pt_BR).The file
naming scheme follows that of the Java specification, and is as follows:
my_application_ll.properties
where ll is the lowercase language code (fr, pt, en, and so on), or
my_application_ll_CC.properties
where ll is the lowercase language code (fr, pt, en, and so on), and CC is the
uppercase country code (CA, US, BR, and so on).
8. Have each of the files translated into the corresponding languages.
9. To import your resource bundle into your process application, open the
localization resource file in Process Designer and click Import.
10. Browse to your updated .zip file to select it and click Finish. If you select to
overwrite the values for all existing keys, then for any given language, key
values in the imported files that do not match the existing key values will replace
the existing values. Any new keys are added to the existing set of keys in the
existing localization resource.
774
11. If there are any missing keys in any of the translated files, warnings are
displayed. Click each of the languages that are flagged with a warning to see
which key translations are missing. If you do not supply translations for these
keys, the default value is displayed in any interfaces that reference this key.
What to do next
After you have created your localization resources, you can associate them with
your coach views or human services by going to the Variables tab.
Parent topic:Localizing process applications
775
Procedure
1. Go to the Variables tab of the coach view or human service that contains your
coach, click the plus sign next to Localization Resources and select the
localization resource bundle that contains the strings for your interface.
2. In the Coaches tab of the human service or the Layout tab of the coach view,
select the control that you want to localize.
3. Click Assign a variable next to the Label field and select the localization key
for the control label.
4. Click Assign a variable next to the Documentation field and select the
localization key for the hover help text for this control.
5. Save your human service or coach view, and test your localizations by changing
your language settings, and verifying that the localized strings appear in your
interface.
Parent topic:Localizing process applications
776
Procedure
1. In the Variables tab for the coach view, click the plus sign next to Localization
Resources and select the localization resource bundle that contains the strings
for your interface.
2. In the Layout tab of the coach view, select the configuration option that you want
to localize.
3. Click Assign a variable next to the Label field and select the localization key
for the configuration option label.
4. If you are grouping a set of configuration options together under a group heading,
you can localize the group name by clicking Assign a variable next to the
Group field and selecting the localization key for the configuration option group
label.
5. Click Assign a variable next to the Documentation field and select the
localization key for the configuration option hover help text.
6. Save your coach view and test your localizations by reusing the coach view in a
coach or coach view, changing your language settings, and verifying that the
localized strings appear with your configuration property.
Parent topic:Localizing process applications
777
Version context
Each snapshot has unique metadata to identify the version (referred to as version
context). You assign that identifier, but IBM recommends using a three-digit numeric
version system in the format <major>.<minor>.<service>. See the topics about
naming conventions for a more detailed description of this versioning scheme.
IBM Business Process Manager assigns a global namespace for each process
application. The global namespace is specifically either the process application's tip
or a particular process application snapshot. The version name used by the server
cannot be longer than seven characters, so the assigned name is an acronym that
uses characters from the snapshot name that you assigned. Snapshot acronyms
areidentical to their snapshot names if the snapshot names conform to the
recommended IBM VRM style and are not more that seven characters. For
example, a snapshot name of 1.0.0 will have an acronym of 1.0.0, and a snapshot
name of 10.3.0 will have the acronym of 10.3.0. The snapshot acronym will be
guaranteed to be unique within the context of the process application within the
scope of the Process Center server. For that reason, you cannot edit the snapshot
acronym.
778
pure lifecycle management perspective), but the content and function are the same.
When you install a process application in a cluster, an automatic synchronization of
the nodes is performed.
- Naming conventions
A naming convention is used to differentiate the various versions of a process
application as it moves through the lifecycle of updating, deploying, co-deploying,
undeploying, and archiving.
Parent topic:Building process applications
Related information:
Creating new process applications
Managing snapshots
Versioned modules and libraries
779
Naming conventions
A naming convention is used to differentiate the various versions of a process
application as it moves through the lifecycle of updating, deploying, co-deploying,
undeploying, and archiving.
This section provides you with the conventions that are used to uniquely identify
versions of a process application.
A version context is a combination of acronyms that uniquely describes a process
application or toolkit. Each type of acronym has a naming convention. The acronym
is limited to a maximum length of seven characters from the [A-Z0-9_] character set,
except for the snapshot acronym, which can also include a period.
- The process application acronym is created when the process application is
created. It can be a maximum of seven characters in length.
- The snapshot acronym is created automatically when the snapshot is created. It
can be a maximum of seven characters in length.If the snapshot name meets the
criteria for a valid snapshot acronym, the snapshot name and acronym will be the
same.
Note: When using the mediation flow component version-aware routing function,
name your snapshot so that it conforms to the <version>.<release>.<modification>
scheme (for example, 1.0.0). Because the snapshot acronym is limited to seven
characters, the digit values are limited to a maximum of five total digits (five digits
plus two periods). Therefore, care should be taken when the digit fields are
incremented, because anything beyond the first seven characters is truncated. For
example, a snapshot name 11.22.33 results in a 11.22.3 snapshot acronym.
- The track acronym is automatically generated from the first character of each word
of the track name. For example, a new track created with the name My New Track
would result in an acronym value of MNT.The default track name and acronym are
Main. Deployment to a IBM Process Center server includes the track acronym in
the versioning context if the track acronym is not Main.
A business process definition in a process application is typically identified by the
process application name acronym, the snapshot acronym, and the name of the
business process definition. Choose unique names for your business process
definitions whenever possible. When duplicate names exist, you might encounter
the following problems:
- You might be unable to expose the business process definitions as web services
without some form of mediation.
- You might be unable to invoke a business process definition created in IBM
Process Designer from a BPEL process created in IBM Integration Designer.
The version context varies, depending on how the process application is deployed.
- Naming conventions for Process Center server deployments
On the IBM Process Center server, you can deploy a snapshot of a process
application as well as a snapshot of a toolkit. In addition, you can deploy the tip of
a process application or the tip of a toolkit. (A tip is the current working version of
780
your process application or toolkit.) The version context varies, depending on the
type of deployment.
- Naming conventions for Process Server deployments
On the Process Server, you can deploy the snapshot of a process application. The
process application snapshot acronym is used to uniquely identify the version.
Parent topic:Versioning process applications
781
Stand-alone toolkits
For toolkit snapshot deployments, the version context is a combination of the
following items:
- Toolkit name acronym
- Toolkit track acronym (if a track other than Main is used)
- Toolkit snapshot acronym
Tips
Process application tips are used during iterative testing in Process Designer. They
can be deployed to Process Center servers only.
For process application tip deployments, the version context is a combination of the
following items:
- Process application name acronym
- Process application track acronym (if a track other than Main is used)
- "Tip"
Toolkit tips are also used during iterative testing in Process Designer. They are not
deployed to a production server.
For toolkit tip deployments, the version context is a combination of the following
items:
782
Examples
Resources should be uniquely named and identified externally using the version
context.
- The following table shows an example of names that are uniquely identified. In this
example, a process application tip uses the default track name (Main):Table 1.
Process application tip with default track name
Type of name
Process application name
Process application name acronym
Process application track
Process application track acronym
Process application snapshot
Process application snapshot acronym
Example
Process Application 1
PA1
Main
Any SCA modules associated with this process application tip include the version
context, as shown in the following table:Table 2. SCA modules and version-aware
EAR files
SCA module name
Version-aware name
M1
M2
PA1-Tip-M1
PA1-Tip-M2
Version-aware
EAR/application name
PA1-Tip-M1.ear
PA1-Tip-M2.ear
- The following table shows an example of a process application tip that uses a nondefault track name: Table 3. Process application tip with non-default track name
Type of name
Process application name
Process application name acronym
Process application track
Process application track acronym
Process application snapshot
Process application snapshot acronym
Example
Process Application 1
PA1
Track1
T1
Tip
Any SCA modules associated with this process application tip include the version
context, as shown in the following table:Table 4. SCA modules and version-aware
EAR files
SCA module name
Version-aware name
783
Version-aware
EAR/application name
M1
M2
PA1-T1-Tip-M1
PA1-T1-Tip-M2
PA1-T1-Tip-M1.ear
PA1-T1-Tip-M2.ear
Example
Process Application 1
PA1
Main
Any SCA modules associated with this process application snapshot include the
version context, as shown in the following table:Table 6. SCA modules and
version-aware EAR files
SCA module name
Version-aware name
M1
M2
PA1-PSV1-M1
PA1-PSV1-M2
Version-aware
EAR/application name
PA1-PSV1-M1.ear
PA1-PSV1-M2.ear
- The following table shows an example of a process application snapshot that uses
a non-default track name: Table 7. Process application snapshot with non-default
track name
Type of name
Process application name
Process application name acronym
Process application track
Process application track acronym
Process application snapshot
Process application snapshot acronym
Example
Process Application 1
PA1
Track1
T1
Process Snapshot V1
PSV1
Any SCA modules associated with this process application snapshot include the
version context, as shown in the following table:Table 8. SCA modules and
version-aware EAR files
784
Version-aware name
M1
M2
PA1-T1-PSV1-M1
PA1-T1-PSV1-M2
785
Version-aware
EAR/application name
PA1-T1-PSV1-M1.ear
PA1-T1-PSV1-M2.ear
Example
Process Application 1
PA1
1.0.0
1.0.0
A resource, such as a module or library, has the version context as part of its
identify.
The following table shows an example of two modules and how the associated EAR
files include the version context:Table 2. SCA modules and version-aware EAR files
SCA module name
Version-aware name
M1
M2
PA1-1.0.0-M1
PA1-1.0.0-M2
Version-aware
EAR/application name
PA1-1.0.0-M1.ear
PA1-1.0.0-M2.ear
Version-aware name
PA1-1.0.0-Lib1
PA1-1.0.0-Lib2
PA1-1.0.0-Lib1.jar
PA1-1.0.0-Lib2.jar
786
787
788
789
build a CMIS query that is based on the specified IBM BPM document display
options and then pass it to the service for execution.
- Limitations in working with IBM BPM documents
There are some limitations in working with IBM BPM documents. In most
situations, you can successfully work around these limitations.
790
791
Description
Documents
Checked Out
Documents
Documents
Created
Folders or documents
Deleted
Folders or documents
Updated
Folders or documents
792
793
store
The IBM BPM content store supports a subset of the inbound content event types
that are supported by external Enterprise Content Manager systems. Event
subscriptions for the IBM BPM content store can be created only by using the
IBM_BPM_Document type.
Case management functions are only available if you have IBM BPM Advanced with
the Basic Case Management feature installed.
The inbound content event types that are supported for the IBM BPM content store
are listed in the following table:
Inbound content event
types
Checked In
Description
Documents
Checked Out
Documents
Documents
Class Changed
Folders or documents
Created
Folders or documents
Deleted
Folders or documents
Filed
Folders
794
Frozen
Documents
Locked
Folders or documents
Security Updated
Folders or documents
Unfiled
Folders
Unlocked
Folders or documents
Updated
Folders or documents
Version Demoted
Documents
Version Promoted
Documents
795
IBM_BPM_Docume Integer
nt_ParentDocument
Id
IBM_BPM_Docume String
nt_FileType
IBM_BPM_Docume String
nt_FileNameURL
IBM_BPM_Docume Boolean
nt_HideInPortal
IBM_BPM_Docume Integer
nt_ProcessInstance
Id
Description
The numeric
document identifier
in IBM Business
Process Manager.
Value
The identifier is
automatically
calculated and
cannot be
overwritten.
The numeric
The identifier is
document identifier automatically
of the parent
calculated and
document in IBM
cannot be
BPM.
overwritten.
Indicates whether
Optional. If a value
the document
is not set, the value
content contains
"FILE" is used.
"FILE" or references
"URL".
The file name of the Optional.
original document
or URL. It is
recommended that
this property is set.
Indicates whether
Optional. If a value
the document
is not set, the
should be hidden
document is shown
from Process
in Process Portal.
Portal.
The process
Optional. If a value
instance identifier. If is not set, the
this property is set, document is
the document is
associated to an
associated to the
instance (if the
lifecycle of the
document creation
process instance.
is performed in the
The document
context of that
content can only be process instance).
viewed by those
The value can only
users who have
be set on document
authority to view the creation.
process instance.
796
IBM_BPM_Docume String[]
nt_Properties
IBM_BPM_Docume Integer
nt_UserId
The additional
properties of the
document. The key
and value should be
separated by the
comma (,)
character.
The creator or last
modifier of the
document.
797
Optional.
Optional. If a value
is not set, the user
ID of the caller is
used. The caller can
be the human
service user (or the
engine user when a
human service is
not used).
798
Procedure
1. In the Content Integration node, specify the following options:
- Server: IBM BPM document store
- Operation: Check-out document.
2. In the Server Script node, populate the implementation with the code that is
required to update the content or properties.
3. In the Content Integration node, specify the following options:
- Server: IBM BPM document store
- Operation: Check-in document. The document ID (private working copy ID)
that is returned by the check-out document operation must be used as input to
the check-in document operation.
What to do next
For sample code and information about working with IBM BPM document properties,
see Working with the IBM_BPM_Document_Properties property. For sample code
and information on working with content streams, see The IBM_BPM_Document
document type.
799
800
// Initialize the
ECMMultiValue variable that will carry the name value pairs for the BPM properties
801
if(tw.local.document.properties[i].objectTypeId == "IBM_BPM_Document_Properties"){
// If there was only a single name-value pair stored in the BPM properties, then
// a string is returned.
// There is a string in the format "name,value". Store it into the output variable.
var nameValuePair = bpmProperties.split(",");
}else{
// Else, there is an instance ECMMultiValue. Introspect this object and store everything into the
// NameValuePair list.
for (var j = 0; j < bpmProperties.value.listLength; j++) {
802
is
803
// contains the document instance retrieved previously (by a get document operation, for example).
var bpmPropertiesEntry;
for (var j = 0; j < tw.local.document.properties.listLength; j++) {
if(tw.local.document.properties[j].objectTypeId == "IBM_BPM_Document_Properties"){
bpmPropertiesEntry = tw.local.document.properties[j];
break;
}
}
// If there is a single BPM document property, the ECMProperty value will be a string.
// This is made an instance of ECMMultiValue, which enables the update to be
// handled generically even if the number of properties eventually changes.
if(typeof bpmPropertiesEntry.value == 'string') {
var value = bpmPropertiesEntry.value;
bpmPropertiesEntry.value = new tw.object.ECMMultiValue();
bpmPropertiesEntry.value.value = new tw.object.listOf.ANY();
bpmPropertiesEntry.value.value[0] = value;
// Cycle through the properties and update them with new values.
var bpmPropValues = bpmPropertiesEntry.value;
for (var j = 0; j < tw.local.bpmProperties.listLength; j++) {
if(updateValue.name == nameValuePair[0]){
// Found the property, set the new value.
804
// Now that the properties have been updated, populate the update operation with the input
805
Procedure
1. To specify a search condition in the Content Filter page, complete the following
steps:
A. In the Search Criteria section, select the Properties property.
B. For the operator, select the contains property.
C. Specify the search value in the format BPM_property_name,search_value. For
example, the search condition approved,true would find all BPM documents
that have a BPM property name approved with a value of true.
Additional information about specifying search criteria is found in the topic
"Building a query for an Enterprise Content Management search operation."
2. To provide your own CMIS search query, use the same format that is used for the
search condition in the Content Filter page. For example, the following search
query will return the same results as the above search condition:ANY
IBM_BPM_Document_Properties IN('approved,true')
806
807
808
809
Procedure
1. Select the Servers tab from the Process App Settings editor. You see the
Process App Settings editor when you first click Open in Designer from a
newly created process application in the Process Center. Alternatively you can
select Process App Settings from the drop-down list on the toolbar in Process
Designer.
2. Beneath the Servers heading click Add. Beneath the Server Details heading,
enter a meaningful name for server. From the drop-down list in the Type field,
select Enterprise Content Management Server. Enter a meaningful description
of the server in the Description field. This field is optional.
3. Beneath the Server Locations heading, enter the following information.
- Environment Type: The environment of the Enterprise Content Management
server. Enter the server location information (host name, port, context path,
whether it is a secure server, repository name, user ID, and password) for each
environment type. These environments are described in the IBM Business
Process Manager overview. Modifying the IBM Process Server environment
type shows you how to change these types. If you do not provide values for
these environments, the values from the default environment type are used.
- Default: If you do not provide values for the following environment types,
default values are used.
- Development: The environment where you develop your services.
- Test: The environment where you test your services.
- Staging: The environment where you deploy your services for pre-production
testing.
- Production: The environment where your services are deployed for use by
your organization.
- Hostname: The host name of the Enterprise Content Management server.
Specify an IP address or a host name and domain. For example:
myHost.labwide.ibm.com
810
- Secure server: Specify whether you want your service to be secure, that is, to
use the Hypertext Transfer Protocol Secure (HTTPS) protocol by selecting this
check box. If you select the HTTPS protocol, you must configure HTTPS
security, as described in Accessing an IBM Case Manager server using the
Secure Sockets Layer (SSL).
- Repository: The name of your repository.
- Userid: The user ID to connect to the Enterprise Content Management server.
- Password: The password of the user ID connecting to the Enterprise Content
Management server.
- Always use this connection information: If selected, which is the default, only
this user ID and password are used for authentication. For example, a human
service, which your service is associated with when a Document List or
Document Viewer is configured, also has a user context. An administrator uses
the Manage Users function to specify human service users. Selecting this check
box means this user ID and password overrides any other user information.
4. Click Test Connection to confirm the connection to the server works.
5. Save your work. From the menu, select File > Save All. You can change these
settings at run time. See Changing ECM server settings using the Process Admin
Console.
Parent topic:Integrating with Enterprise Content Management (ECM) systems
Related information:
Authentication scenarios
Building a service that integrates with an ECM system or the IBM BPM document
store
811
812
Authentication scenarios
IBM Business Process Manager provides three ways that you can grant access to
an Enterprise Content Management (ECM) server. You can set a user ID and
password for the process application that is recognized by the Enterprise Content
Management system. You can design a business process to use personal
credentials to control access to specific documents and folders on the ECM server.
Or, you can design a business process that uses each method of authentication for
different steps in the process.
The IBM Business Process Manager system and the Enterprise Content
Management system are separate systems. If shared security is not configured, the
IBM BPM system does not recognize Enterprise Content Management users and
vice versa. Being authenticated on one system does not mean that a user or user
group is also authenticated on the other system. Consider the way you want to
share Enterprise Content Management information with IBM BPM users before you
design your application.
In some scenarios, you want to project the user identity of the currently acting
human user from the BPM system to the ECM system. This approach allows users
to create and access private documents, provides records for audits, and allows
fine-grained access control on the Enterprise Content Management server. In other
scenarios, the actual user identity of the human user who is working with IBM BPM
does not matter in the Enterprise Content Management system. In such cases, it
might be enough to use a static system identity that represents the BPM system. For
example, the business process might generate public documents or perhaps all
BPM users need to see the same collection of documents in a user interface.
When you configure access to an Enterprise Content Management server in IBM
Process Designer, you set a user ID and password (see the related links for more
information about this task). If you use the default setting, the ID and password do
not need to be valid on the BPM system, but they must be valid for the Enterprise
Content Management server. At the end of the settings is a check box labeled
Always use connection information specified here. When that check box is
selected, which it is by default, that user ID and password are attached to all calls
made from that process application to the ECM server. The advantage of this
method is that the Enterprise Content Management server is immediately available
for use by the actions in the process application. However, do not use this option if
you want to restrict which documents or folders individual users can see and use.
Using this method, a static user name and password as defined in the process
application settings is the only credential that can be submitted from IBM BPM to the
Enterprise Content Management server. There is no way of telling the ECM system
who the current "real" user is. Therefore, even if you set up single sign-on (SSO),
there is no way of fine-grained access control and gathering auditing data by
individual user.
Clear the Always use connection information specified here check box if you
want to restrict which documents or folders individual users or specific user groups
can see and use. When that check box is not selected, the IBM BPM system uses
individual user names and IDs for authentication and projects the identity to the
813
Enterprise Content Management server. Now you can assign specific tasks to users
who can see only the documents and folders that they need to complete those
tasks. A service that is started by a user task in a BPD runs under the security
context of the user who claimed and started the task.
You can design a business process definition to use both authentication methods,
depending on the context. If the Always use connection information specified
here check box is not selected, authorization depends on how you model your
business process. By choosing the context from which the call is made, you can
restrict access to the Enterprise Content Management server to a user ID specified
in the process application server settings or to a task owner. If the Enterprise
Content Management service is called by a system task in a BPD, the user that is
identified in the process application settings is used. If the Enterprise Content
Management service is called by a human task, by a coach, or by an integration
service within a user task, the task owner identity is propagated to the ECM system.
In this latter case, the user ID and password set on the process application are
ignored. Calls that use the task owner identity fail if the BPM and ECM systems do
not have shared security.
Parent topic:Outbound interactions with Enterprise Content Management systems
Related information:
Adding an Enterprise Content Management server
Changing ECM server settings using the Process Admin Console
The 99Local.xml and 100Custom.xml configuration files
Changing IBM Process Server properties in 100Custom.xml
814
816
Procedure
1. Create a Human service.
2. Select a Coach from the palette and drag it onto the canvas. Enter an
appropriate name for the coach and save your work. Tip: Do not select the
817
What to do next
You might want to update bindings in the documents coach view by using a script,
for example, because the values for the inputs to your search service changed. If
you run a script to update the binding, you must change the previous value. In the
following JavaScript example, the columns are updated by appending text that
changes the older values.
tw.local.cmisQueryString = "SELECT cmis:name, cmis:objectId ";
if (tw.local.photoCatagory) tw.local.cmisQueryString = tw.local.cmisQueryString + ", PhotoCatagory";
if (tw.local.photoSubject) tw.local.cmisQueryString = tw.local.cmisQueryString + ", PhotoSubject";
if (tw.local.photoLocation) tw.local.cmisQueryString = tw.local.cmisQueryString + ", PhotoLocation";
if (tw.local.photoDate) tw.local.cmisQueryString = tw.local.cmisQueryString + ", PhotoDate";
818
The following steps show how to create a search service for the Document List view.
1. To ensure that you have the correct input and output variables and types, copy
the Default ECM Search Service to your process application.
2. Rename the Default ECM Search Service to an appropriate name, for example,
MySearch.
3. Complete one of the following steps:
- If you configured the Document List view for the IBM BPM document store,
configure the search operation that is defined in the existing IBM BPM
documents Content Integration step.
- If you configured the Document List view for an external ECM server, then add a
Content Integration step to the ECM documents path and configure the search
operation with an Enterprise Content Management server.
4. Use the auto-map function to create the map between the input and output
service parameters and the variables.
819
Procedure
1. Select any service from the library area that supports Content Integration steps.
The following services contain a Content Integration step.
- Select Implementation in the library section and then +. From the menu, select
Integration Service
- Select User Interface and then +. From the menu, select Ajax Service.
- Select User Interface and then +. From the menu, select Human Service.
Enter a name for the service on the following dialog box and click Finish. The
editor opens with the Diagram view in focus.
2. From the palette, drag a Content Integration step to the canvas and provide a
meaningful name for it.
3. Click Implementation in the Properties view. Under Enterprise Content
Management Server, <Use data mapping> is the default selection in the Server
field. It means that in the Data Mapping tab section, the Server name input map
is enabled and editable. You can pass a server name by using a variable in that
field.Alternatively, you can select one of the following server types in the Server
field.
- IBM BPM document store
- The name of an ECM server
Information about the IBM BPM document store is found in the topic "The IBM
BPM document store."
If you want to select the name of an ECM server but no ECM servers are
available for selection, you can add a server in the Process App Settings editor by
820
selecting the Use the Process Application Settings editor to add a server link
and then clicking the Servers tab. After adding the server, click Save and then
switch to the service editor canvas again and select the server from the Server
field. Information about adding an ECM server is found in the topic "Adding an
Enterprise Content Management server."
4. Under Content Operation, select an appropriate ECM operation. The following
table displays the name of each ECM operation and indicates whether the
operation is available for external ECM systems and the IBM BPM document
store.
Operation name
Add document to
folder
Cancel check-out
document
Description
Adds a document
to a folder.
Releases a
document from the
check-out state,
which makes it
possible for other
users to work with
it.
Check-in document Checks in a
document, giving
all users access to
it.
Check-out
Checks out a
document
document; only the
person who
checked it out can
use it.
Copy document
Copies a
document.
Create document Creates a
document.
Create folder
Creates a folder.
Delete document
Deletes a
document.
Delete folder
Deletes a folder.
Get all document
Gets all versions of
versions
a document.
Get document
Gets a document
that matches a
document identifier.
Get document
Gets a stream of
content
data that is the
content of the
document.
Available for
external ECM
systems?
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Yes
No
Yes
Yes
Yes
Yes
No
Yes
Yes
Yes
No
Yes
Yes
Yes
Yes
Yes
821
Get documents in
folder
Get folder
Yes
No
Yes
No
Yes
No
Yes
No
Yes
Yes
Yes
Yes
Yes
No
Yes
Yes
No
No
Yes
Yes
Yes
Yes
Yes
Yes
5. Click Data Mapping. In this section you can create the map between the
variables for input and output. These variables need to be created. You can
create them manually by yourself or use the auto-map function. The auto-map
function creates private variables for the business objects, which are used by the
service you create. Click the auto-map icon to create these private variables.
822
What to do next
As with any service, if you have errors at run time, use catching error events to
handle errors thrown by a content integration step. A content integration step may
raise an error with error code ECMError and error data of type ECMError. See
Handling errors in services.
823
Procedure
1. After specifying a search operation in an Enterprise Content Management service
and selecting a server name, click the Content Filters tab.
2. In the left column, select the search node you want to create your query for, if you
created more than one search step.
3. Beneath Build Search Filters complete the fields appropriate to your query.
- In the Method of creating search field, select one of the following:
- Content Filters: (Default) Select if you want to use the fields on this Content
Filters page to define your search.
- Data Mapping: Select if you are experienced in writing Content Management
Interoperability Services (CMIS) queries and want to write your own handcoded query (see the query section of the CMIS specification for information on
the syntax).Selection will disable the fields in the Content Filters page and
make the CMIS query Input Mapping field editable on the Data Mapping tab.
- Under Object Type, select the type of object for the search. These types are
also discussed in the input and output fields described in Data mapping in
Enterprise Content Management operations.
- Document: A type of document. For example, the server could have an email
type of document for storing critical information sent by email. Click Select and
choose the document type from those available on the server. Examine your
application to decide what document type to select. For example, an
application about insurance claims might select insurance forms.
- Folder: A type of folder that contains documents. For example, the server
could have a security type of folder for containing documents related to
security. Click Select and choose the folder type from those available on the
server.
- Under Properties, click Add to see a list of properties for the type you selected
previously. Select additional properties based on your application. Using the
application about insurance claims mentioned previously, you might want to add
the property of when the insurance claim was made. As you select a property, it
appears as a column in the pane beneath Properties along with sample data
from the selected Enterprise Content Management server. Columns are added
from left to right. The layout of the result set, the sorting of items in columns, and
the priority of which column is sorted first, second, third and so on is described
in the following table.
824
The sorting priority of the result set can alternately be done by selecting Result
set order specified by process variable and mapping to a variable containing
the sorting priority. The content of this variable is a CMIS query following the
standard CMIS syntax (see the link to the CMIS standard page in the Data
Mapping description). This option is helpful for having the sorting priority set at
run time. You may also use JavaScript.
- Under Search Criteria, you can specify constraints for specific properties by
selecting Add Search Criterion. For example, you might want to only search for
objects whose Current State is equal to Working. Match criteria lets you select
all or any as a match criteria. All returns items matching all the criteria specified
in the filter. Any returns items matching any single field in the filter. The match
criteria does not affect the search result columns shown in the Properties table
though it will affect the rows.
4. Save your work. File > Save All.
What to do next
Using Document List and Document Viewer views, you can turn your search into a
list of documents that a user can browse, select and view.
If the Search operation is used with a Document List view, the ID column is not
shown in the Document List. However, the ID column should not be removed from
the query. The IDs provide the links to each document in the content repository. An
825
826
In this example, we take a generic search result and extract the IDs of all the
documents found, and store them in an array. Document IDs are a basic piece of
information used by most of the ECM operations.
When there is no return type specified for the search operation, the
ECMSearchResult.resultSet field contains an ECMSearchResultSet object, which in
turn holds a list of ECMSearchResultRow objects.
The ECMSearchResult.propertyMetadata has the column information as specified in
the CMIS query, and can be used to search for specific columns, as shown below.
/* Property metadata is captured by the ECMPropertyMetadata business object */
var columnMetadata = tw.local.searchResult.propertyMetadata;
/*
* Check if a search result found. Find which column contains the ID column and
* save its index so we can retrieve the right value from each row.
*/
if (tw.local.searchResult.numItems > 0) {
for (var i = 0; i < columnMetadata.length; i++) {
if (columnMetadata[i].queryName == 'cmis:objectId') {
idColumnIndex = i;
break;
}
827
/* Set the return list of ECMSearchResultBO to output the output variable and we are done */
var resultSet = tw.local.searchResult.resultSet;
828
mimeType
fileName
content
Description
The length of the original (nonencoded) content length in
bytes. If the property is set, the
length must be a positive
number. If the length is
unknown, the property must not
be set.
The MIME media type of the
content stream. For the primary
content of a document, the
MIME media type should match
the value of the property
cmis:contentStreamMimeType.
For example, application/pdf.
The file name of the content
stream. For the primary content
of a document, the file name
should match the value of the
property
cmis:contentStreamFileName.
The value of the document. It
must be of type String Base64
and encoded in UTF-8.
The following example code fragments can be used in a script activity to get and set
values:// Script sample code to set and encode the document content
var value = "abc";
var bytesValue = new Packages.java.lang.String(value).getBytes("UTF-8");
var content64 = Packages.org.apache.commons.codec.binary.Base64.encodeBase64(bytesValue);
829
830
Add document to
folder
Cancel check-out
document
Check-in document
Check-out document
Copy document
Create document
Create folder
Delete document
Delete folder
Get all document
versions
Get document
Get document
content
Get documents in
folder
Get folder
Get folder by path
Get folder tree
Get type definition
Get type
descendants
Move document
Move folder
Remove document
from folder
Search
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Yes
No
Yes
No
Yes
No
Yes
Yes
Yes
Yes
Yes
Yes
No
Yes
Yes
Yes
Yes
Yes
No
No
No
Yes
Yes
Yes
Yes
Yes
No
No
No
Yes
Yes
831
No
Set document
content
Update document
properties
Update folder
properties
Yes
Yes
Yes
Yes
Yes
No
Check-in document
Input:
- Private working copy document ID (ECMID): A unique identifier for the private
working copy of the document object.
- Major (Boolean): (Optional) An indicator of the version of the checked-in
document. If set to true then the document is a major version, which is the default.
- Content stream (ECMContentStream): (Optional) A stream of data containing the
content of the document such as a word processing document or an image.
Information about the ECMContentStream data type is found in the topic Working
with document content.Note: If you have made updates to a document and your
ECM system is Microsoft SharePoint, you cannot pass the content stream
parameter with the Check-in document operation. You must first pass the
content stream parameter with the Set document content operation and then
832
Check-out document
Input:
- Document ID (ECMID): A unique identifier of a document object.
- Server name (String): The name of the server containing the document.
Output:
- Private working copy document ID (ECMID): A unique identifier for a private
working copy of the document object.
Copy document
Input:
- Document ID (ECMID): A unique identifier of a document.
- Parent folder ID (ECMID): A unique identifier of the parent folder for the
document.
- Name (String): Optional - A new name for the copied document. When the name
is set, it overrides the name in the ECMProperty list (if specified).
- Versioning state (String): (Optional) A name that defines the version of the
document. Valid values are:
- major: (Default) The copied document is a major version. If versioning is disabled,
the major value is not a valid versioning state and you must use the none value
instead.
- minor: The copied document is a minor version.
- checkedout: The copied document has a checked-out state.
- none: The copied document cannot be versioned.
- Properties (ECMProperty []): (Optional) A set of named properties that can be in
any order.
- Server name (String): The name of the server for the document.
Output:
- Document ID (ECMID): A unique identifier of the new document.
Create document
Input:
- Object type ID (ECMID): This identifier corresponds to a class name defined on
the ECM system that is used to create a document. For example, the value
833
Create folder
Input:
- Object type ID (ECMID): The ID of the object's type. It's base type must be a
folder.
- Parent folder ID (ECMID): The identifier of the parent folder.
- Name (String): The name of the folder.
- Properties (ECMProperty []): (Optional) A set of named properties that can be in
any order.
- Server name (String): The name of the server for the folder.
Output:
- Folder ID (ECMID): A unique identifier of the new folder.
834
Delete document
Input:
- Document ID (ECMID): A unique identifier of a document object.
- All versions (Boolean): (Optional) States whether all versions of the document
are to be deleted. The default is true.
- Server name (String): The name of the server containing the document.
Output:
- No output is returned.
Delete folder
Input:
- Folder ID (ECMID): A unique identifier of a folder object.
- Server name (String): The name of the server containing the folder.
Output:
- No output is returned.
Get document
Input:
- Document ID (ECMID): A unique identifier of the document.
- Server name (String): The name of the server containing the document.
Output:
- Document (ECMDocument): The document object.
Get folder
Input:
- Folder ID (ECMID): A unique identifier of a folder.
- Server name (String): The name of the server containing the folder.
Output:
- Folder (ECMFolder): The folder object.
Move document
Input:
- Document ID (ECMID): A unique identifier of a document.
- Target folder ID (ECMID): A unique identifier of the new folder for the document.
- Source folder ID (ECMID): A unique identifier of the present folder for the
document.
- Server name (String): The name of the server containing the document and
folders.
Output:
- No output is returned.
Move folder
Input:
- Folder ID (ECMID): The identifier of the document.
- Target folder ID (ECMID): The identifier of the new parent folder.
- Source folder ID (ECMID): The identifier of the old parent folder.
- Server name (String): The name of the ECM server that identifies the
corresponding ECM repository.
Output:
- No output is returned.
837
Search
Input:
- CMIS query (String): Text containing a Content Management Interoperability
Services (CMIS) query. See Building a query for an Enterprise Content
Management search operation.
- Return type (String): (Optional) An indicator that determines the type of items
returned by the search result. The following types can be specified:
- ECMSearchResultRow: (Default) An ECMSearchResultRow contains an array of
values. The name is the query name of the Content Management Interoperability
Service (CMIS) property used in the SELECT clause of the query or the name
can be determined by introspection of the metadata.
- Business object name: When the name of a business object type is specified then
an instance of that type is returned. The properties returned by the search are
mapped to the properties of the business object if their names match.
- Search all versions (Boolean): (Optional) An indicator that specifies which
document versions are to be considered. If true then it considers the latest and
older versions of the document or documents in the search. If false, which is the
default, then only the latest version is returned.
- Max items (Integer): (Optional) An indicator that specifies the maximum number
of items to return. The default, -1, states that the default number is taken from the
ECM server.
- Skip count (Integer): (Optional) An indicator that specifies the number of potential
items to be skipped over before returning any items. The default is 0.
- Include allowable actions (Boolean): (Optional) An indicator that retrieves the
available actions for the objects returned in the query. This parameter is only
offered with the IBM BPM content store. The default is false.
- Server name (String): The name of the server containing the documents and
folders.
Output:
- Search result (ECMSearchResult): An object containing a set of qualifying items.
The content is different based on the value of the Return type input parameter. The
default is an object of type ECMSearchResultRow.
838
839
840
841
842
agent that works with your event subscription. A content undercover agent (UCA)
is used to initiate a BPM Start or Intermediate event when specific content changes
occur on an ECM server. It is conceptually similar to a message undercover agent,
but it has a specialized Content marker to differentiate it from a Message marker.
- Adding a content event to a BPD
In a BPD, a content event is used to catch or throw interactions with an enterprise
content management (ECM) system. You can add one of several types of content
events, such as a start event, intermediate event, boundary event, or event
subprocess start event.
- The ECMContentEvent business object
The ECMContentEvent business object is included in the Content Management
toolkit, which is used to gain access to Enterprise Content Management (ECM)
types and services. The resources of the toolkit are required to allow a business
process developed in Process Designer to work with an Enterprise Content
Management system. The ECMContentEvent business object is used to pass
generic ECM event data to an event subscription service and content undercover
agent (UCA). The business object is passed unchanged as BPMN event data into
the process if it is not modified, mapped, or replaced by the service or UCA.
843
Procedure
1. Create an event subscription by completing the following steps:
A. Open a process application in Process Designer.
B. In the library area of the Designer page, click the plus (+) icon beside
Implementation and then select Event Subscription. The New Event
Subscription wizard opens.
C. In the Name field, specify a name for the new event subscription.
D. Click Finish. The new event subscription is displayed in the Implementation
library list (under Event Subscription) and the event subscription opens in the
Event Subscription editor.
E. In the ECM Server drop-down list, select one of the following server types to
associate with the event subscription:
- IBM BPM document store
- The name of an ECM server
Information about the IBM BPM document store is found in the topic "Working
with IBM BPM documents."
If you want to select the name of an ECM server but no ECM servers are
available for selection, you can add a server in the Process App Settings editor
by selecting the Use the Process Application Settings editor to add a
server link and then clicking the Servers tab. After adding the server, click
Save and then switch to the event subscription editor again and select the
server from the ECM Server drop-down list. Information about adding an ECM
server is found in the topic "Adding an Enterprise Content Management
server."
F. If you selected the name of an ECM server in the ECM Server drop-down list,
select either the default Document event class or the Folder event class in
844
the Content UCA. The following figure shows an integration service as it might
appear after it has been fully implemented:
For both a general system service and an integration service, the signature of
both the service and the Content UCA includes an Input named contentEvent
with a business object type of ECMContentEvent.
E. If you chose to create an integration service, select the decision gateway in the
canvas and open the Properties tab and the Implementation pane, then
define the decision conditions for the decision gateway. Other than perhaps
renaming the labels of the components, this is all that is required to complete
the implementation of the integration service.
F. Click Save.
3. Add a content event to a BPD by completing the following steps:
A. In the library area of the Designer page, click the plus (+) icon beside
Processes and then select Business Process Definition. The New Business
Process Definition wizard opens.
B. In the Name field, specify a name for the new BPD.
C. Click Finish. The new BPD is displayed in the Process library list (under
Business Process Definitions) and the BPD opens in the BPD editor.
D. In the canvas, select the existing Start event or select the Start Event or
Intermediate Event icon in the palette and drag the event to the canvas.
E. Click the Properties tab and then click Implementation. The Implementation
panel opens.
F. In the Start Event Details or Intermediate Event Details section, change
None to Content. The event in the diagram changes to display a Content
marker icon.
G. Beside the Attached Content UCA area in the Content Trigger section, click
Select and then select the Content UCA that was automatically created when
you created the attached service. It has the same name as the service.
(Additional information about creating a Content UCA is found in the topic
Creating and configuring an undercover agent for a content event.)
H. In the canvas, ensure that the Content event is selected, then click the
Properties tab and click Data Mapping. The Data Mapping panel opens.
846
I. Click the variable selector icon on the right side of each field to map each
undercover agent output variable to a local variable in the BPD.
J. If you are working with an intermediate event, select the variable that you want
to use to correlate the event with the BPD instance. The variable selected for
correlation is identified by an assignment symbol. This correlation ensures
that the parameter values of the runtime message are passed to the correct
BPD instance. (IBM Business Process Manager only requires one variable
mapping to correlate the event.)
K. Click Save.
4. Test the new components by completing the following steps:
A. Switch to your event subscription in the event subscription editor.
B. Click Save.
C. Click Test Subscription. Test Event Subscription opens, which contains
fields that are populated with the selections that you made in the Event
Subscription editor. The selections represent the data that will be returned from
the ECM server.
D. In the Object field, accept the default object or select a different object on the
ECM server.
E. Click Test. If the event subscription is defined correctly, a simulated incoming
ECM event is triggered and the following message is displayed: An inbound
ECM event has been successfully simulated for the event
subscription.
The attached service, content UCA, and start or intermediate event are
subsequently invoked, which leads to either a response from an existing BPD
instance or the creation of a new BPD instance. You can view BPD instances
in the Inspector view of Process Designer.
Parent topic:Performing modeling tasks for inbound events
847
Procedure
1. Open the Process Designer desktop editor.
2. Create a new event subscription by completing the following steps:
A. Open a process application.
B. In the library area of the Designer page, click the plus (+) icon beside
Implementation and then select Event Subscription. The New Event
Subscription wizard opens.
C. In the Name field, specify a name for the new event subscription.
D. Click Finish. The new event subscription is displayed in the Implementation
library list (under Event Subscription) and the event subscription opens in the
Event Subscription editor.
3. Configure the new event subscription by completing the following steps in the
Event Subscription editor:
A. In the ECM Server drop-down list, select one of the following server types to
associate with the event subscription:
- IBM BPM document store. The IBM BPM document store supports most
Content Management Interoperability Services (CMIS) operations. It is used
in developing business process definitions.
- IBM BPM content store. The IBM BPM content store supports all CMIS
operations. It is used for developing case management applications. It is only
available in IBM Business Process Manager Advanced.
- The name of an ECM server
Information about the IBM BPM document store and the IBM BPM content
store is found in the topic "Working with IBM BPM documents."
848
If you want to select the name of an ECM server but no ECM servers are
available for selection, you can add a server in the Process App Settings editor
by selecting the Use the Process Application Settings editor to add a
server link and then clicking the Servers tab. After adding the server, click
Save and then switch to the event subscription editor again and select the
server from the ECM Server drop-down list. Information about adding an ECM
server is found in the topic "Adding an Enterprise Content Management
server."
B. If you selected the name of an ECM server in the ECM Server drop-down list,
select either the default Document event class or the Folder event class in
the Event Class drop-down list.
C. If you selected the name of an ECM server in the ECM Server drop-down list,
select either the top-level default Document object type or select a different
object type in the Object Type drop-down list. (If the drop-down list is
disabled, the server is probably unavailable.)
D. If you selected the name of an ECM server in the ECM Server drop-down list
and you want to include all of the subtypes of the selected object type, ensure
that the Include Subtypes check box is selected.
E. In the Event type drop-down list, accept the Created default event type for
your ECM server or select a different event type. (If the drop-down list is
disabled, the server is probably unavailable.) For more information about the
available event types, see Content event types.
F. If you want to select an existing service for your event subscription that will run
and respond to incoming ECM events, click Select in the Attached service
area and then select the name of a service, such as General System Service
or Integration Service.
G. If you want to create a new service for your event subscription that will run and
respond to incoming ECM events, complete the following steps:
1. In the Attached Service area, click New. The New Service for Event
Subscriptions wizard opens.
2. In the Name field, accept the default name (which is the same as the event
subscription name) or type a different name for your new service.
3. If you want to create a general system service that will directly invoke the
content UCA without first querying the ECM server for additional
information, select Create a service that directly invokes a UCA.
However, if you want to create an integration service that will first query the
ECM server for additional information before determining whether a UCA
should be invoked, select Create a service that queries the ECM server
before invoking a Content UCA.
4. Click Finish. The new service and a new content UCA of the same name
are created. The new service opens in the service editor. If you chose to
create a general system service, it is already fully implemented and consists
of a start event, an end event, and an Invoke UCA step that will invoke the
new content UCA. However, if you chose to create an integration service, it
is partially implemented and it consists of several components, such as an
Integration step, a decision gateway step, and an Invoke UCA step to invoke
the content UCA.
849
H. If you want to test your event subscription and ensure that the attached
service, content UCA, and start and intermediate events are all operating
correctly, complete the following steps:
1. Click Test Subscription. Test Event Subscription opens, which contains
fields that are populated with the selections that you made in the Event
Subscription editor. The selections represent the data that will be returned
from the ECM server.
2. In the Object field, accept the default object or select a different object on
the ECM server.
3. Click Test. If the event subscription is defined correctly, a simulated
incoming ECM event is triggered and the following message is displayed:
An inbound ECM event has been successfully simulated for the
event subscription.
The attached service, content UCA, and start or intermediate event are
subsequently invoked, which leads to either a response from an existing
BPD instance or the creation of a new BPD instance. You can view BPD
instances in the Inspector view of Process Designer.
I. By default, event subscriptions are exposed to all users. This means that when
any user performs an action that corresponds to the event type that is
specified in the Event Type drop-down list (such as creating a document), a
document event or a folder event will be fired. If you selected the IBM BPM
document store in the ECM Servers drop-down list, you cannot change the
default behavior of event subscriptions being exposed to all users. However,
for the IBM BPM content store or an ECM server in the ECM Servers dropdown list, you can specify that you only want events to be fired for designated
users who are named in an existing team. This is accomplished by clicking
Select in the Exposing area and then choosing the name of the team.
Alternatively, you can create a new team for designated users by completing
the following steps:
1. In the Exposing area, click New. The New Team wizard opens.
2. In the Name field, type a name for the new team.
3. Click Finish. The Team page opens.
4. In the Team page, define the team by following the instructions in the topic
Creating a team.
J. Click Save.
Parent topic:Performing modeling tasks for inbound events
Related information:
Building a service that integrates with an ECM system or the IBM BPM document
store
Working with IBM BPM documents
Adding an Enterprise Content Management server
850
Associated object
types
Documents
Description
An event produced
when a user checks
in a document.
Checked Out
Documents
An event produced
when a user checks
out a document.
Check Out Canceled Documents
An event produced
when a user cancels
the checkout of a
document.
Class Changed
Folders or documents An event produced
when a user changes
the class of the
object. For example,
the user can change
the class when
checking in a
document.
Classify Completed Documents
An event produced
when a document is
added using an entry
template with the
Auto-Classify option
set.
Created
Folders or documents An event produced
when a user adds an
item to the object
store.
851
Deleted
Filed
Frozen
Locked
Publish Completed
Publish Requested
852
Security Updated
State Changed
Unfiled
Unlocked
Updated
853
Version Demoted
Documents
Version Promoted
Documents
An event produced
when a document
version is demoted.
An event produced
when a document
version is promoted
to a released version.
The document can be
promoted to a
released version from
the information page
or when adding or
checking in. Note:
The Filed and Unfiled
event triggers are not
supported for
subscriptions. If you
need to use these
triggers, you can
create the
subscription using the
Enterprise Manager
for the Content
Engine. In addition,
you can create
subscriptions with the
Publish Request
event using
Enterprise Manager
for the Content
Engine.
854
855
Procedure
1. Open the Process Designer desktop editor.
2. Open a process application in the Designer view.
3. Click the plus (+) icon beside Processes and then select Business Process
Definition. The New Business Process Definition wizard opens.
4. In the Name field, specify a name for the new BPD.
5. Click Finish. The new BPD is displayed in the Process library list (under
Business Process Definitions) and the BPD opens in the BPD editor.
6. In the canvas, select the existing Start event or select the Start Event or
Intermediate Event icon in the palette and drag the event to the canvas.
7. Click the Properties tab and then click Implementation. The Implementation
panel opens.
8. In the Start Event Details or Intermediate Event Details section, change None
to Content. The event in the diagram changes to display a Content marker icon.
9. Beside the Attached Content UCA area in the Content Trigger section, click
Select to select an existing content undercover agent (UCA). (If you select an
existing message UCA, the intermediate event in the diagram is changed from a
content event to a message event.) Alternatively, you can click New to create a
content UCA. For information about creating content UCAs, see Creating and
configuring an undercover agent for a content event.
10. In the BPD editor canvas, ensure that the Content event is selected, then click
the Properties tab and click Data Mapping. The Data Mapping panel opens.
856
11. Perform the data mapping tasks by completing the following steps:
A. Click the variable selector icon on the right side of each field to map each
undercover agent output variable to a local variable in the BPD.
B. If you are working with an intermediate event, select the variable that you
want to use to correlate the event with the BPD instance. The variable
selected for correlation is identified by an assignment symbol ( ). This
correlation ensures that the parameter values of the runtime message are
passed to the correct BPD instance. (IBM Business Process Manager only
requires one variable mapping to correlate the event.)
For undercover agents that are implemented using a complex variable rather
than a service, you can select the complex variable or the top-level child
properties of the variable for mapping or correlation.
12. Click Save.
Parent topic:Performing modeling tasks for inbound events
857
858
859
event handler, refer to the FileNet Content Manager information center topics
Events and Subscriptions.
Procedure
1. Identify which ECM events you need your event handler to support. The following
table lists the IBM BPM names for the ECM events that are supported by IBM
BPM.Table 1. ECM events supported by IBM BPM
Supported ECM events
CheckedIn
CheckedOut
CheckOutCanceled
ClassChanged
ClassifyCompleted
Created
Deleted
Filed
Frozen
Locked
PublishCompleted
PublishRequested
SecurityUpdated
StateChanged
Unfiled
Unlocked
Updated
VersionDemoted
VersionPromoted
Folder or Document
Folder or Document
Document
Document
Tip: For more details about the event types, refer to the REST API ECM event
resource reference topic.
2. For each event that you need notifications of, identify the corresponding event
name that is used by your ECM system.
3. Plan how your ECM event handler will obtain the information required to connect
to the IBM BPM system. For example, the FileNet Content Manager event
handler, BPMEventHandler, loads the connection information defined in a
properties file that is stored in FileNet Content Manager.
4. Plan your code to receive event notifications in your ECM system and translate
them into the corresponding calls to the appropriate IBM BPM system. For
example, in the FileNet Content Manager event handler BPMEventHandler, the
BPMEventType method translates the FileNet Content Manager event types to the
corresponding IBM BPM event notification API method names.
5. Write your event handler according to your requirements and the event handling
framework provided by your ECM system. Refer to the documentation for your
ECM system.
6. Deploy and configure your event handler on your ECM system.
7. Verify that your event handler is called for the required events, and that it
transmits the events to the appropriate IBM BPM server.
8. Verify that you can create an IBM BPM process that receives the event
notifications from your ECM system. Perform Creating and configuring event
subscriptions.
Parent topic:Performing administrative tasks for inbound events
Related reference:
REST API: ECM Event Resource - POST Method
Related information:
Adding an Enterprise Content Management server
Building a service that integrates with an ECM system or the IBM BPM document
store
Adding events to a BPD
861
Overview
The event handler is for IBM FileNet Content Manager version 5.1.
Supported events
The following table lists all ECM events that are supported by IBM BPM, and the
corresponding FileNet Content Manager events. Use the table to identify the
FileNet Content Manager events that you need to subscribe to, and the names that
are used in Process Designer to identify the same events in IBM BPM.
Table 1. Mapping between supported ECM events and FileNet Content Manager
events
ECM events
Object types that the
supported by IBM
event can apply to
BPM
(com.ibm.bpm.BPME
ventType)
CheckedIn
Document
CheckedOut
Document
CheckOutCancelled Document
ClassChanged
Folder or Document
ClassifyCompleted Document
Created
Deleted
Filed
Frozen
Locked
PublishCompleted
Folder or Document
Folder or Document
Folder
Document
Folder or Document
Document
PublishRequested
Document
SecurityUpdated
Folder or Document
StateChanged
Unfiled
Unlocked
Updated
VersionDemoted
Document
Folder
Folder or Document
Folder or Document
Document
VersionPromoted
Document
862
Corresponding
FileNet Content
Manager events
(com.filenet.api.event
s)
CheckinEvent
CheckoutEvent
CancelCheckoutEve
nt
ChangeClassEvent
ClassifyCompleteE
vent
CreationEvent
DeletionEvent
FileEvent
FreezeEvent
LockEvent
PublishCompleteEv
ent
PublishRequestEve
nt
UpdateSecurityEve
nt
ChangeStateEvent
UnfileEvent
UnlockEvent
UpdateEvent
DemoteVersionEven
t
PromoteVersionEve
nt
Copy the event handler to a suitable location on your FileNet Content Manager
server.
bpm.server.uri=http\://bpm_server_name\:9080
bpm1.example.com.
2. Store the properties file in the ECM system. There are several ways that you can
store the properties file. For example, you can use the Workplace XT portal to
store the properties file by performing the following actions:
A. Using a browser, log in to the Workplace XT portal at the URL http://
filenet_server_host_name:port/WorkplaceXT.
B. Select the object store where you want to store the configuration file. The
default object stores are DESIGN and TARGET. Select the same object store
where the case solution is located.
C. Expand the object store, then either add a new folder or select a suitable
existing folder where you want to store the properties file.
D. Click the Add Document... action or icon.
E. Click Choose File. On the local file system, locate the properties file, select it,
and click OK, then Next.
F. Click OK, then Add.
3. Make a note of the document ID for the properties file. For example, if you are
using the Workplace XT portal, perform the following actions.
A. Right-click the name of the properties file that you stored, for example,
bpmserver1.properties, and select Properties.
B. Make a note of the document ID, or select and copy it to a convenient
clipboard or text file. Remember: You must specify this document ID later
when you configure the binding of the event handler to the event subscription.
E. If you already created an event action for the BpmEventHandler event handler,
select it using the drop-down list, then click Next. Otherwise, create a new
event action for the BpmEventHandler event handler by performing the
following steps:
1. Click New, enter an appropriate name for the action event, for example,
BpmEventHandler, and click Next.
2. For Handler Java Class Name, enter
com.ibm.bpm.integration.filenet.BPMEventHandler, select
Configure Code Module, then click Next.
3. Click Browse/Add to locate the event handler JAR file filenet-bpmevent-handler-51.jar that you copied from your IBM BPM server, then
click Next, Finish.
4. Verify that the newly created event action is selected, and click Next.
F. Accept the default settings in Specifiy Additional Properties by clicking Next.
G. Click Finish to complete creating the subscription.
3. Set the User String property for the subscription to the document ID for the
properties file.
A. In the Subscription Name list, select the subscription that you named in step
2b.
B. Click Properties.
C. In the list of properties, locate the property with the Property Name of User
String.
D. Click the ... button, and enter (or preferably copy and paste) the value of the
document ID for the properties file. This is the string that you noted during
Creating the connection information document.Important: If you want different
IBM BPM servers to receive event notifications, you will have a connection
properties file for each IBM BPM server. Make sure that you provide the
document ID for the appropriate server's connection properties file.
E. Click OK.
F. Click OK.
Remember: If you ever modify the connection information in the properties file,
because the new version gets a new document ID, you must change the User
String to identify the new document ID.
Now notifications of all subscribed events are sent to the appropriate IBM BPM
server.
Parent topic:Performing administrative tasks for inbound events
Related reference:
REST API: ECM Event Resource - POST Method
Related information:
Adding an Enterprise Content Management server
Building a service that integrates with an ECM system or the IBM BPM document
store
Adding events to a BPD
865
866
867
868
CMIS capabilities
IBM FileNet Content Manager supports the optional CMIS capabilities that are
described in the following table:
CMIS Capability
Best practices
The best practices for developing client applications for IBM CMIS for FileNet
Content Manager are described in the topic Best practices for developing client
applications.
Reference
869
Information about the IBM CMIS for FileNet Content Manager implementation of the
OASIS CMIS standard is found in the topic IBM CMIS for FileNet Content Manager
implementation of the OASIS CMIS specification.
870
CMIS capabilities
IBM Content Manager supports the optional CMIS capabilities that are described in
the following table:
CMIS Capability
IBM Content
Manager
ACL
none
AllVersionsSearchabl true
e
Changes
none
ContentStreamUpdat pwconly
ability
GetDescendants
GetFolderTree
Join
true
true
none
Multifiling
PWCSearchable
true
false
PWCUpdatable
false
Query
metadataonly
BPM Considerations
Not applicable
Not applicable
Documents must be
checked out for
updates
Queries cannot
include any JOIN
clauses
Renditions
none
Unfiling
true
VersionSpecificFiling false
Private working
copies of a document
are not searchable
The private working
copy of a document
is not updatable
The CONTAINS()
predicate function is
not supported
Not applicable
Known limitations
The known limitations of the IBM CMIS for Content Manager implementation are
described in the topic IBM CMIS for Content Manager limitations.
871
Reference
Information about the IBM CMIS for Content Manager implementation of the OASIS
CMIS standard is found in the topic Programming IBM CMIS for Content Manager
applications.
872
Capabilities
Alfresco Community supports the optional CMIS capabilities that are described in
the following table:
CMIS Capability
ACL
AllVersionsSearchabl
e
Changes
ContentStreamUpdat
ability
GetDescendants
GetFolderTree
Join
Alfresco Community
manage
false
BPM Considerations
Not applicable
none
anytime
Not applicable
Multifiling
PWCSearchable
true
false
PWCUpdatable
Query
Renditions
Unfiling
true
bothcombined
read
false
true
true
none
Queries cannot
include any JOIN
clauses
Private working
copies of a document
are not searchable
Not applicable
Documents are
always filed in a
folder
VersionSpecificFiling false
873
Reference
For information about the Alfresco implementation of the OASIS CMIS standard, see
the Alfresco topic Alfresco CMIS.
874
Setup
Your Microsoft SharePoint installation may use a URL convention for the CMIS web
service endpoint that is not expected by IBM BPM. See the topic "Accessing the
SharePoint CMIS provider from IBM BPM" for information on how to establish the
addressability of the CMIS web service for IBM BPM.
CMIS capabilities
Microsoft SharePoint supports the optional CMIS capabilities that are described in
the following table:
CMIS Capability
Microsoft SharePoint
ACL
manage
AllVersionsSearchabl false
e
Changes
ContentStreamUpdat
ability
GetDescendants
GetFolderTree
Join
objectidsonly
anytime
Multifiling
false
PWCSearchable
PWCUpdatable
Query
Renditions
true
true
bothseparate
none
false
true
none
BPM Considerations
Not applicable
A search will only be
applied to the latest
(major) version of a
document
Not applicable
Not applicable
Queries cannot
include any JOIN
clauses
Documents can only
reside in one folder
875
Not applicable
Unfiling
false
Documents are
always filed in a
folder
VersionSpecificFiling false
Reference
For information about the Microsoft SharePoint implementation of the OASIS CMIS
standard, see the Microsoft topic Content Management Interoperability Services
(CMIS) connector overview (SharePoint Server 2010).
876
Note: The above Kerberos URL is intended to provide an example of the naming
convention that is used with SharePoint CMIS web service URLs. However, this
help topic does not include any information about Kerberos authentication. It
explains how to map to the URL syntax conventions that are used by IBM BPM.
When IBM BPM attempts to contact the SharePoint server using the following URL,
a connection cannot be made because the web service address is not known:
http://hostName:portNumber/_vti_bin/cmis/soap/RepositoryService
The URL Rewrite Module enables the URL to be rewritten in the SharePoint format
that is shown in the following example:
http://hostName:portNumber/_vti_bin/cmis/soap/RepositoryService.svc/basic
To enable the URL Rewrite Module to rewrite incoming request URLs from IBM
BPM, the following tasks need to be completed:
- Download URL Rewrite Module 2.0 for Microsoft IIS 7
- Define the rewrite rules in IIS Manager
- Access the SharePoint CMIS Provider from IBM Process Designer
To perform these tasks, complete the steps in the following procedure.
Procedure
877
1. Download URL Rewrite Module 2.0 for IIS 7 by completing the following steps:
A. Verify that you have IIS 7 installed.
B. If Microsoft URL Rewrite Module 2.0 is not already installed in your IIS 7
installation, download it from one of the following web pages and then install it
using the instructions that are found at one of the following web pages:
- (x64) http://www.microsoft.com/enus/download/details.aspx?id=7435
- (x86) http://www.microsoft.com/enus/download/details.aspx?id=5747
2. Define the rewrite rules in IIS Manager by completing the following steps:
A. On your desktop, select Start > Administrative Tools > Internet Information
Services (IIS) Manager. IIS Manager opens.
B. Select a connection.
C. Select IIS > URL Rewrite.
D. Select Rule > Inbound rules > Blank rule.
E. In the Name area, specify CMIS URL rewrite rule.
F. In the Match URL section, complete the following steps:
1. In the Requested URL drop-down list, select Matches the Pattern.
2. In the Using drop-down list, select Regular Expressions.
3. In the Pattern field, specify the following pattern:^.*cmis/soap/(.*)$
4. Select Ignore case.
G. In the Conditions section, complete the following steps:
1. Click Add. The Add Condition dialog box opens.
2. In the Condition input field, specify the following condition input:{R:1}
3. In the Check if input string drop-down list, select Does Not Match the
Pattern.
4. In the Pattern field, specify the following pattern:(.*).svc(.*)
5. Select Ignore case.
6. Click OK.
H. In the Actions section, complete the following steps:
1. In the Action type drop-down list, select Rewrite.
2. In the Rewrite URL field, specify a rewrite URL that is appropriate for your
configuration. For example:{R:0}.svc/kerberos
{R:0}.svc/basic
879
880
881
- Visualize variables
Select and visualize the local input, output, or private variables used in a process.
- Visualize tag groups
Select and visualize the tag groups defined for a process.
- Keyboard shortcuts for data visualization
In the data visualization diagram in the web browser window, you can perform
many of the available actions by using keyboard shortcuts.
Parent topic:Testing and debugging process applications
882
Visualize variables
Select and visualize the local input, output, or private variables used in a process.
Procedure
1. Open a business process definition (BPD) in IBM Process Designer.
2. Click the Data Visualization button in the upper right corner. Alternatively, click
Playback > Visualize Process to view the data visualization diagram.The data
visualization diagram opens in a new web browser window.
3. Select Data from the drop-down list in the selection area on the left side in the
browser window. Under Variable, click Inputs, Outputs, or Private and select
the input, output, or private variables that you want to visualize on the activities in
the diagram on the right side.Variables are displayed as colored icons in the
diagram. The activities in the selected BPD that have the same variables are
represented by icons of the same color. Up to three icons are displayed on either
side of each activity.
4. Click the down arrow spinners below the third icon on either side to display the
next three icons. Click the up arrow spinners on either side to view the earlier
icons.
5. Click any colored icon to slide and display the labels that contain the actual
variable names for all same-color icons.
6. Click a subprocess within a process in the diagram to visualize that subprocess.
The input and output variables are global to the process; if you browse into a
subprocess the same variables are displayed. Private variables can be defined on
the main process and the subprocesses inherit them. However, private variables
defined on a subprocess are visible only to that particular subprocess.
7. Click the Minimize button on the left side to hide the variables list and view only
the data visualization diagram. Use the zoom in or zoom out bar in the upper right
corner to enlarge or reduce the diagram view in the browser window.
Parent topic:Visualizing process data
Related information:
Creating custom business objects in Process Designer
Declaring and passing variables
883
Procedure
1. Open the Process Designer desktop editor.
2. Open a business process definition (BPD) in the Designer view.
3. Click the Data Visualization button in the upper right corner. Alternatively, click
Playback > Visualize Process to view the data visualization diagram.The data
visualization diagram opens in a new web browser window.
4. Select Tag Groups from the drop-down list in the selection area on the left side in
the browser window. Under Tag Group Value, select the tag group and its values
that you want to visualize in the diagram on the right side.Tag groups are
represented by labels on top of the activities in the diagram. The activities in the
selected business process definition (BPD) that have the same tag groups display
labels that have the same color. Where an activity is mapped to more than one
tag group, the labels that contain the tag groups are displayed stacked on top of
each other in a tab.
Note: A script activity can call a service synchronously from a BPD using the
tw.system.executeServiceByName() JavaScript function. To visualize the tag
groups defined for such a service, an annotation that includes the service name
must be added to the script activity. Add the //@ServiceName annotation followed
by the exact name of the service, to the first line of the script activity. For
example, //@ServiceName "myService", where myService is the exact name of
the service.
5. Click the tab of stacked labels in the diagram to display all the labels on top of the
activity.
6. Click a subprocess within a process in the diagram to visualize that subprocess.
Tag groups are specific to the services within a process. If the process and its
subprocesses use the tagged service, the tag groups are displayed for both.
7. Click the Minimize button on the left side to hide the tag groups list and view only
the data visualization diagram. Use the zoom in or zoom out bar in the upper right
corner to enlarge or reduce the diagram size in the browser window.
Parent topic:Visualizing process data
Related information:
Tagging library items
884
885
e+1, 2, 3, and so on
To browse through the selection area on the left side in the browser window:
1. Press Tab to access the drop-down list for data variables and tag groups.
2. Use the Up arrow key to select Data and the Down arrow key to select Tag
Groups.
3. Press Tab to browse through the list of check boxes available for the data
variables or tag groups. Inside each check box, press Space to toggle the
checked or cleared state. Use Tab or Shift+Tab to move up and down the list of
check boxes.
To browse through the breadcrumb area at the top of the browser window:
1. Press Tab to access the first process in the breadcrumb area.
2. Press Tab to browse forward in the list of processes and Shift+Tab to browse
backwards.
3. Press Enter on any process entry in the list to visualize the diagram of that
particular process.
Use the following shortcut keys to browse in New Tag or Tag Group in Process
Designer:
- Press Tab to toggle between the text boxes for tag group name and value, the
Check if this is a Tag group check box, OK, and Cancel.
- Press Space to select or clear the check box.
- Press Enter on OK or Cancel to submit or cancel your inputs.
886
Description
When you run a process, you can view
all previously run and currently running
instances on the IBM Business Process
Manager servers in your environment.
You can manage running instances by
halting and then resuming them, for
example. You can also manage
previously run instances by filtering or
deleting specific records.
For a selected instance, see the currently
running step and then move forward
through the process, evaluating process
execution step by step. A tree display of
the process combined with indicators
called tokens in the process diagram
make it easy to understand where you
are in the process. You also have the
advantage of seeing the variables used
in each step and their corresponding
values (where applicable).
See the following topics to learn more about using the Inspector interface.
- Managing process instances
Manage current and previously running instances of your process on the server
that you select.
- Restricting access to debugging for services
For services other than human services, you might need to limit access to
debugging functionality in the Inspector in IBM Process Designer. Use the IBM
Business Process Manager configuration file (99Local.xml) to control which users
887
have the ability to debug services. To edit the settings, find the debug section in
the 99Local.xml file. Copy it to the 100Custom.xml file, and then make the
necessary changes there.
- Stepping through a process
Step through process execution to ensure that your BPD works as expected.
- Debugging a process
Use the Inspector debugging feature to examine each underlying process or
service in each step of your process execution to perform a more thorough
inspection than stepping through your process.
- Resolving errors
Find the source of errors generated when running your business process definition
(BPD) and resolve them.
- Inspector reference
Learn how to access and use each feature provided by the Inspector.
Parent topic:Testing and debugging process applications
Related information:
Restricting Inspector actions for online Process Servers
888
Procedure
1. Open a business process definition in IBM Process Designer.
2. Click the Run button in the upper right corner.
3. When IBM Business Process Manager prompts you to change to the Inspector
interface, click Yes.Note: Click the check box if you want IBM Process Designer
to change interfaces without prompting for approval.
In the Process Instances tab, you can see all currently active and completed
process instances.
The Inspector shows the running and completed instances on the Process Center
Server for all snapshots (versions) of the current BPD.
4. To view instances running on a different server or to view instances for a different
version of the BPD, select a different server or snapshot from the drop-down
menus in the toolbar.Important: Remote Process Servers must be connected to
your Process Center to be available. To learn how to connect to remote Process
Servers, see Using wsadmin commands to customize the Process Server settings
used to connect to Process Center in IBM Business Process Manager and Using
the administrative console to customize the Process Server settings used to
connect to Process Center. To run a process on a different server using the
Inspector, you must first deploy the process application snapshot that contains
the process that you want to run as described in Installing snapshots on a
connected process server. If you click the Run icon while All versions is selected
from the list of snapshots, the Inspector runs the most recent snapshot of the
BPD on the Process Center Server. For remote Process Servers, the snapshots
available are limited to the snapshots that are deployed on that server.
5. To control instances, select an instance from the list and then click the toolbar
option that you want. For example, if you want to stop an instance that you
started earlier, click the instance and then click the Terminate Button to terminate
the instance. Tip: You can also filter the list of instances shown by providing a
name in the Instance Name field and using the Status drop-down menu.
Parent topic:Running and debugging processes with the Inspector
889
Default setting
<enabled>true</enabled true
>
<enforce-debugrole>false</enforcedebug-role>
false
890
Description
Establishes whether
debugging of services is
enabled. If set to false ,
when you attempt to debug
a service in the Inspector
in IBM Process Designer,
IBM BPM simply runs the
service without providing
any debugging feedback.
Establishes whether IBM
BPM users who do not
belong to the Debug group
(defined in the following
setting) can access
debugging functionality. By
default, this element is set
to false , which allows
users who do not belong to
the Debug group to access
debugging functionality.
So, by default, all users
have access to debugging
for services. If you want to
limit access to users who
are members of the Debug
group, set this element to
true .
<debugrole>debug</debugrole>
debug
The debug section of the 99Local.xml file is shown in the following example: <server
merge="mergeChildren">
<debug merge="mergeChildren">
<!-- Indicates whether or not debugging of services is enabled. If this is false then debugging a service will simply run
the service, and the
debugging functions will be turned off. -->
<enabled merge="replace">true</enabled>
<!-- Defines whether or not users that do not belong to the debug role can access
debugging functions for services. -->
<enforce-debug-role merge="replace">true</enforce-debug-role>
<!-- Specifies the role a user must be a member of to debug a service. Only one
user role can be defined. If enabled is false, or is enforce-debug-role is
false then this has no effect.
If enabled and debug-role is true, then a user belonging to this role will
have access to debugging functions. A user that does not belong to this
role will not have access to debugging functions, hence the service will run
as it would normally.
If you do not specify any value for the debug role this will disable the
debugging functions.
-->
<debug-role merge="replace">debug</debug-role>
891
</debug>
</server>
892
Procedure
1. Open a business process definition in IBM Process Designer.
2. Optional: To view instances running on a different server or to view instances for
a different version of the BPD, select a different server or snapshot from the
drop-down menus in the toolbar.Important: Remote Process Servers must be
connected to your Process Center to be available. To learn how to connect to
remote Process Servers, see Using wsadmin commands to customize the
Process Server settings used to connect to Process Center in IBM Business
Process Manager and Using the administrative console to customize the
Process Server settings used to connect to Process Center. To run a process on
a different server using the Inspector, you must first deploy the process
application snapshot that contains the process that you want to run as described
in Installing snapshots on a connected process server. If you click the Run icon
while All versions is selected from the list of snapshots, the Inspector runs the
most recent snapshot of the BPD on the Process Center Server. For remote
Process Servers, the snapshots available are limited to the snapshots that are
deployed on that server.
3. Click the Run button in the upper right corner.
4. When IBM Business Process Manager prompts you to change to the Inspector
interface, click Yes.Note: Select the check box if you want IBM Process
Designer to change interfaces without prompting for approval.
5. In the Process Instances tab, click the new or received task and then click the
Run button. In some cases, you might need to select a user account or provide a
password for a specific user account in order to run a task. This is controlled by
lane assignments and routing for activities. See Assigning teams to BPDs and
lanes and Assigning teams to BPD activities for more information.
6. Complete the task when it runs. For example, if the task generates a Coach,
enter requested values and complete the form. When the task is complete, you
return to the Inspector.
7. Click the Refresh icon in the toolbar. The Inspector shows the progress by
moving the token to the next step in both the diagram and the navigation tree.
Note: If your BPD includes an attached timer event, you can right-click the timer
event token in the navigation tree and select Fire Timer to trigger the event.
8. You can expand subprocesses, event subprocesses, and linked processes as
you step through their contents by double-clicking on the activity in the diagram
893
view. Even if you do not expand a subprocess activity, you still step through
activities contained in the subprocess.
9. To see the variables passed from step to step, click the process node in the
navigation tree.
10. Right-click a variable and then click Show in Execution Evaluator. The
Inspector opens the Execution Evaluator tab and shows the values for the
parameters within the selected variable.
You can use the Execution Evaluator to inspect the variable values as they
change through the flow of the business process definition. Note: You can also
manipulate variables in the Execution Evaluator using JavaScript expressions to
validate your process implementation. To do so, enter the JavaScript expression
and click the Run icon at the top of the Evaluator. The results are displayed in
the bottom pane of the tab.
11. In the Process Instances tab, click the task for the next step, and then click the
Run task icon.
12. Click the Refresh icon in the toolbar. You can tell that the business process
definition is complete when the final step has a status of Closed and there are
no active tokens in the diagram or navigation tree.
Parent topic:Running and debugging processes with the Inspector
894
Debugging a process
Use the Inspector debugging feature to examine each underlying process or service
in each step of your process execution to perform a more thorough inspection than
stepping through your process.
Procedure
1. Open a business process definition (BPD) in IBM Process Designer.
2. Click Run.
3. When IBM Business Process Manager prompts you to change to the Inspector
perspective, click Yes.Note: Select the check box if you want IBM Process
Designer to change interfaces without prompting for approval.
4. In the Process Instances tab, click the new task, and then click Debug task.
Depending on the task implementation, complete the steps in one of the following
procedures:
- If the task that you are debugging is implemented as a client-side human
service, the client-side human service Inspector opens in a browser window,
pausing on the first step after the Start event. Complete the following steps to
debug the client-side human service:
A. When prompted, select the user that you want to debug the client-side
human service as. You can choose to debug the service as the user that
claimed the task or as a different user. For a different user, the user name
that you select must belong to a user group that has read access to the
corresponding process application. You are logged in to the web browser
using the selected user name.
B. Use the actions on the sidebar to proceed with the debugging of the clientside human service. See Debugging client-side human services.
C. Before running each step in the service flow, examine the variable values that
are displayed on the sidebar at each point to determine whether they are
expected.
D. To move to the next activity in the service flow, click Step Over .
E. If this activity is a coach, complete the coach and trigger the boundary event
to transition out of the coach. The Inspector moves to the next step in the
service flow.
895
F. (Optional) To view the progress of the service execution, you can click the
Designer tab in the upper-left corner of the browser window. On the clientside human service diagram, the followed path is highlighted and a colorcoded token marks the current position in the service flow.
G. Complete the debugging of the client-side human service in the Inspector
browser window.
H. When the debugging of the client-side human service is complete, go back to
the BPD Inspector window and click Refresh to update the task status
accordingly. The Inspector moves to the next step in the process flow. At the
same time, the Inspector shows progress through the service, using tokens in
the diagram and navigation tree.
- If the task that you are debugging is not implemented as a client-side human
service, complete the following steps to debug the service:
A. If the service does not require user input, click Run to run all code and logic
and then view the end values.
B. If the service requires user input, use the Step button and complete the fields
for any associated coaches to step through each part of the service.
The BPD Inspector opens a debugging session in a browser window. At the
same time, the Inspector opens the currently executing service in the Services
in Debug tab and shows progress through the service, using tokens in the
diagram and navigation tree.
5. To continue through the rest of your BPD, click the Process Instances tab in the
Inspector, and then repeat the actions in step 4. In the debugger session in your
browser, you can see data that you enter into any displayed coaches and the
values that cause the underlying logic in the services and BPD to proceed along
the available paths. This insight can be extremely helpful when issues are
identified and you need to find the point at which a process instance is not
functioning as you expected.
Parent topic:Running and debugging processes with the Inspector
896
Resolving errors
Find the source of errors generated when running your business process definition
(BPD) and resolve them.
Procedure
1. When the execution of a BPD does not complete successfully, the Inspector
displays the error in the BPD diagram and also in the navigation tree.
2. Click the error shown in the navigation tree to open the Runtime Error Information
window. The Runtime Error Information window indicates where the error
happened and it also provides a link to the service in which the error occurred so
you can go directly to the source.
3. Click More in the Runtime Error Information window to show additional details
about the error, such as stack trace details. You can also use the Copy to
Clipboard button if you want to paste the contents of the window to a text file or
support ticket. The Inspector copies all information to the clipboard, including
stack traces.
Parent topic:Running and debugging processes with the Inspector
897
Inspector reference
Learn how to access and use each feature provided by the Inspector.
The following image shows the Inspector interface and each major functional area:
The following table describes each numbered area in the preceding image of the
Inspector interface in IBM Process Designer:
Table 1. Description of numbered areas on the Inspector interface image
Area number
1
Description
Shows the currently active and
previously run process instances on the
Process Center Server or connected
Process Server in the Process Instances
tab. The highlighted instance is the
currently selected instance, which means
any action you perform or any data
shown in the other areas of the Inspector
apply to this instance. (The Services in
Debug tab becomes active only if you
select the Debug icon for a particular
task.)
Use the Instance Name field and the
Status drop-down menu to control the list
of instances displayed in the Process
Instances tab. For example, if you want
to see only active process instances that
include the word employee in their name,
type employee in the Instance Name field
and select Active from the Status dropdown menu.
898
899
Function
Pauses the selected process instance.
Resumes a suspended process instance.
Stops a running process instance.
Removes any record of the selected
process instance.
900
Understanding tokens
In the Inspector interface, tokens indicate where the runtime instance is currently
executing-both in the diagram of the BPD or service and in the navigation tree of the
instance execution. The following general rules apply to tokens:
- If a token is on a step, that step is in an active state. Until the step has been
completed, the process instance cannot proceed.
- If a token is on a conditional sequence flow, the target step is enabled-it can
receive the token-because the condition on the sequence flow was met. Conditions
are evaluated after the step has been completed but before the process enters the
outgoing sequence flow.
- A process instance can generate several tokens. For example, a split can cause
two tokens to be generated. These tokens are merged into a single token when the
process reaches a join gateway.
901
902
903
Globalization
To ensure that applications can be used in multiple geographical locations and
cultures, globalization support is built in through appropriate design and
implementation of systems, software, and procedures. IBM Business Process
Manager provides globalization support for single- and multi-byte character sets and
for bidirectional transformation including contextual support, support for text layout
transformation, and calendar support for Hebrew and Hijri.
For more information about using translated IBM Business Process Manager
components, see Known issues for translated IBM BPM components.
- Bidirectional support in IBM Business Process Manager
Scripts such as Hijri and Hebrew, where the general flow of text proceeds
horizontally from right to left, are called "bidirectional" scripts. The attribute
"bidirectional" (bidi) is used for scripts, but by association, the languages that use
bidirectional scripts are called bidirectional languages. Although bidi text runs in
both directions, the right-to-left direction is the norm.
- Contextual support
IBM BPM offers contextual bidi support for languages such as Arabic and Hebrew,
where the general flow of text proceeds horizontally from right to left.
- Troubleshooting Process Designer and Process Center connectivity
Resolve problems starting Process Designer, for example during login, by using
various techniques such as correcting invalid connection information or logging
errors that are captured with log4J or java.util.logging.
- Enabling error logging in Process Designer
You can configure IBM Process Designer to log errors by using log4J or
java.util.logging. You can then examine the logs to troubleshoot problems
with Process Designer.
Parent topic:Building process applications
904
905
Procedure
1. From the palette, add a server script to a service, such as a heritage human
service.Note: This transformation can be performed from any server-side service.
To perform a text layout transformation in a client-side human service, include a
call to a server-side service, such as an integration service, from within your
client-side human service flow.
2. In the Variables tab for the service, add an input string variable for the string to
be transformed.
3. In the Diagram tab, select the server script.
4. In the Implementation tab of the Properties view, enter the script for calling the
bidi engine to implement the transform. For example:tw.local.Var =
tw.system.bidiTransformation(tw.local.Var,"input_bidi_format", "outputBidiFormat", symmetricSwapping)
5.
What to do next
To test your service, wire it to a coach that has an input variable and text control that
is bound to the transformed string variable, then run the coach.
Parent topic:Bidirectional support in IBM Business Process Manager
906
907
Contextual support
IBM BPM offers contextual bidi support for languages such as Arabic and Hebrew,
where the general flow of text proceeds horizontally from right to left.
Contextual support ensures that when a first typed character is Hebrew or Arabic,
control orientation and typing direction are right-to-left, and that the text alignment is
right. The following is a list of the different kinds of contextual support that IBM BPM
provides.
- Contextual support for names of diagram elements ensures correct display of bidi
text not only in properties but also in diagram.
- Contextual support in notes ensures right-to-left text direction of text inside the
notes.
- When a new activity is dragged from the palette and dropped onto the business
process definition (BPD) canvas, contextual typing of the activity name is possible
inside the BPD diagram.
- Contextual typing is supported in descriptions in Process Center.
Parent topic:Globalization
908
If you see a connection error after you log in, try one of the following tasks:
- Confirm that you are using the correct user name and password.
- Confirm that Process Center is running by accessing it through a browser using the
URL in the form http://hostname:port/ProcessCenter. The default port is
9080.
- Check the eclipse.ini file (in the Process Designer installation directory) to
confirm that the Process Center connection information is correct:
1. Find the installation folder of Process Designer on your local computer, for
example C:\IBM\ProcessDesigner\v8.5.
2. Open the eclipse.ini file and locate -Dcom.ibm.bpm.processcenter.url.
Ensure that the URL prefix (http://hostname:port) is the same as the Process
Center URL prefix.
- Confirm that your Process Designer version matches the Process Center version.
If your administrator upgraded Process Center, you need to upgrade Process
Designer to the same version by accessing Process Center from a browser and
downloading Process Designer.If the two versions are different, you might see a
message similar to the following message: The versions of Process Center("BPM8501-20130922-000036")
and Process Designer ("BPM8500-20130525-092636") do not match.
909
- If you see a blank white Process Designer view or the view does not display fully,
or if you see an HTTP error, press F5 to refresh. If the display continues to be
blank, enable a security option as described in Process Designer window is blank.
- Process Designer communicates with Process Center using the following ports. If
you have a firewall or proxy server, or are running a service that forwards the
ports, check that communication on the following ports is enabled.Table 2. Process
Center ports accessed by Process Designer
Port Name
BOOTSTRAP_ADDRESS
CSIV2_SSL_SERVERAUTH_LI
STENER_ADDRESS
ORB_LISTENER_ADDRESS
SIB_ENDPOINT_ADDRESS
SIB_ENDPOINT_SECURE_AD
DRESS
WC_defaulthost
WC_defaulthost_secure
Default Number
2809
9403
9100
7276
7286
9080
9443
The default ports depend on the server type. Refer to Port number settings in the
WebSphere Application Server information center.
- Examine the IBM Business Process Manager logs for errors or information. See
IBM Business Process Manager log files.
- Turn on Log4J debug level tracing. See Enabling log4J debug tracing
- Use java.util.logging to write errors to a log. See Enabling java.util.logging
910
3. From twappserver.jar, extract the file log4j.xml to the root Process Designer
installation directory.
4. In log4j.xml, change the level value for the com.lombardisoftware logger from
error to debug. The log4j.xml file should be changed from: <logger
name="com.lombardisoftware" additivity="false">
<level value="error" />
</logger>
to: <logger
name="com.lombardisoftware" additivity="false">
5. Open eclipse.ini and point to the updated log4j.xml by adding this line:Dlog4j.configuration=file:<ProcessDesignerInstallationDirectory>/log4j.xml
6. Restart Process Designer, recreate the problem, and note down the time stamp.
The ae.log file should now contain the debug and error messages from Process
Designer.
Enabling java.util.logging
To enable logging for all java.util.logging messages, follow these steps:
1. Close Process Designer.
911
Parent topic:Globalization
Parent topic:Troubleshooting Process Designer and Process Center connectivity
912
Properties
Through the context object, you can access its properties.
Property
context.binding
Description
Provides access to the data object that is
bound to the current view. To access the
data, use the following
call:this.context.binding.get("value")
Where value is a special property name
that returns the bound data object.For
example, if a view is bound to
local.phoneBook.title, the view can
get the title by using the following code:if
(!! this.context.binding){
var title = this.context.binding.get("value")
}
context.contextRootMap
context.element
context.options
913
context.subview[viewid]
context.bpm.system
914
context.bpm.system.settings
context.bpm.team.manager
context.bpm.team.member
context.viewid
915
Functions
Through the context object, you can access its functions.
Function
context.bindingType()
context.broadcastMessage(message)
context.cancelBoundaryEvents()
context.containDiffLoopingContext()
Description
Returns the type of the data binding.
Broadcasts the supplied
message.Important: Do not use this API
to send sensitive or confidential
information.
message(Object). An object that has a
name property.
Cancels the boundary events that have
not been sent to server. If a callback
function was supplied when the boundary
event was triggered, the coach
framework calls the callback function to
update the status of the boundary event.
For more information, see the
context.trigger(callback) function.
Returns a value of true if the following
conditions are true:A coach view that is
bound to a list contains a content box
that contains a coach view.This
contained coach view is bound to the
currentItem of a different list.For
example, the API returns a value of true
for the following structure:TableView (bind to
ListA[])
ContentBox
TextView (bind to ListB.currentItem)
916
context.createView(domNode, index,
parentView)
context.deleteView(domNode)
917
context.getDomNode(uniqueViewId,
optParam)
context.getInheritedVisibility()
context.getOptions(viewDomNode)
context.getStyle()
918
context.bind(type, callbackFunc,
scopeObject)
context.setGroupNotification()
919
context.getSubview(viewId,
requiredOrder)
context.htmlEscape(text)
context.isTrustedSite(origin)
920
921
context.subscribeValidation()
context.trigger(callback options)
this.context.deleteView(subviewDomNode);
923