You are on page 1of 933

Contents

Building process applications


Business process management and case management
Getting started with IBM Process Designer
Process Designer interface
Where to edit Process Designer artifacts
Process Designer tips and shortcuts
Concurrent editing
Setting preferences
Creating new process applications
Creating a process application from a WebSphere Business Modeler process
Creating processes in IBM Process Designer
Modeling processes
Creating a business process definition (BPD)
Adding lanes to a BPD
Adding activities to a BPD
Adding events to a BPD
Modeling process execution paths by using sequence flows
Converging and diverging flows
Example gateways
Implementing activities in a BPD
Implementing a BPD activity as a human service
Creating loops for a BPD activity
Configuring a BPD activity for simple loops
Configuring a BPD activity for multi-instance loops
Assigning teams to BPDs and lanes
Assigning teams to BPD activities
Assigning a dynamically retrieved team
Setting up a routing policy (deprecated)
Defining rules with a routing policy (deprecated)
Assigning an activity to an ad hoc list of users (deprecated)
Configuring conditional activities
Implementing a conditional activity
Managing conditional activities by using the JavaScript API
Creating an unstructured (ad hoc) activity
Example: Starting an unstructured (ad hoc) activity (JavaScript API)
Subprocess types
Modeling non-reusable subprocesses
Working with linked processes
Calling a linked process dynamically
Modeling event subprocesses
Creating a user attribute definition
Validating processes
Task types
Creating user interfaces for a BPD
Building services
Service types

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

Enabling users to perform ad hoc actions (deprecated)


213
Building a sample ad hoc action (deprecated)
214
Testing a sample ad hoc action (deprecated)
216
Modeling event gateways
218
Handling errors using error events
220
Handling errors in BPDs
223
Handling errors in services
225
Error events in models from V7.5.x and earlier
227
Using Service Component Architecture to interact with processes
228
Undercover agents
232
Creating and configuring an undercover agent for a message event
234
Creating and configuring an undercover agent for a scheduled message
event
237
Creating and configuring an undercover agent for a content event
240
Documenting development artifacts
242
Linking to external information
243
Process documentation location links
246
Using external implementations
247
Building a custom application to implement an activity
248
Creating an external implementation
249
Using an external implementation to implement an activity
251
Integrating with web services, Java and databases
253
Creating outbound integrations
254
Integrating with web services
256
SOAP headers
258
Creating implicit SOAP headers for outbound web service integrations
260
Adding SOAP headers to a SOAP request message
261
Retrieving SOAP headers from the SOAP response message 263
Adding a web services server
264
Configuring a Web Service Integration component
268
Security for Web Service Integration steps
271
Web service faults
273
Serialization of objects
275
Setting up message-level encryption
276
Troubleshooting web services outbound web service integrations
279
Considerations when using WSDL with multiple XSD or WSDL imports
281
Troubleshooting XML schema messages for web service integrations
282
Calling a Java method in an integration service
287
Sending attachments using an SMTP server
290
Using Business Process Manager SQL Integration services
291
Creating inbound integrations
293
Building a sample inbound integration
294
Adding a message event to a BPD
295
Creating an attached service
296

Creating an undercover agent


297
Attaching the undercover agent to the message event
298
Creating a caller service
300
Creating an inbound web service
301
Testing the integration
304
Creating implicit SOAP headers for inbound web service integrations
306
Retrieving SOAP headers from an inbound request message
307
Adding SOAP headers to an outgoing response message
309
Posting a message to IBM Business Process Manager Event Manager 311
Publishing IBM Business Process Manager web services
315
Web services compatibility
317
Verifying that the web service is working
318
Calling a web service using a SOAP connector
319
Integrating BPDs with IBM Case Manager cases
322
Adding an IBM Case Manager server
323
Building the IBM Case Manager Integration service
325
Building a query for a search case operation
327
Processing a search case operation result
328
Data mapping in case operations
330
Accessing an IBM Case Manager server using the Secure Sockets Layer (SSL)
332
Designing process interactions for business users
333
Configuring a role-based business user interface
334
Exposing business process definitions
335
Exposing the Ad Hoc Reports dashboard
337
Exposing heritage human services
338
Enabling resumable services
343
Globalizing dashboard names
346
Generating portlets for heritage human services exposed as dashboards
347
Exposing client-side human services
352
Making business data available in searches and views
356
Developing flexible and efficient process applications
358
Configuring activities for inline completion
360
Optimizing BPD execution for latency
363
Automatically starting the user's next task
365
Defining ad hoc actions (deprecated)
367
Setting up collaboration features for business users
369
Enabling Sametime Connect integration
370
Specifying experts for an activity
371
Enabling IBM Connections integration
372
Enabling process instance management
374
Setting the work schedule for a BPD
377
Examples
379
Managing time and holiday schedules
380
Specifying activity due dates
381
Generating names for process instances
383

Enabling processes for tracking and reporting


Tracking IBM Business Process Manager performance data
Data tracking considerations
Autotracking performance data
KPIs and SLAs
Creating custom KPIs
Associating KPIs with activities
Creating SLAs
Setting up autotracking
Tracking groups of process variables
Creating a tracking group
Associating process variables to a tracking group
Creating a timing interval
Sending tracking definitions to Performance Data Warehouse
Exposing performance scoreboards
Defining reports (deprecated)
Defining a custom layout (deprecated)
Building cases
Case management overview
Case management concepts
Scenario: Financial services credit card dispute resolution
Scenario: Automobile insurance claims
Designing a case
Opening Case Designer from Process Center
Creating a case type
Configuring how a case is started
Adding a case type variable or property
Adding case type folders
Assigning teams to a case type
Adding a case activity
Setting preconditions
Implementing an activity
Creating a document type
Example document types
Creating case user interfaces
Testing and debugging a case type
Services to support case management applications
The IBM BPM content store
Case artifacts and the IBM BPM content store
Update restrictions for modifying case artifacts
Creating a team
Using services to define dynamic teams
Setting up a team retrieval service
Setting up a team filter service
Defining team managers
Defining Team rules (deprecated)
Business objects and variables

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

Modeling client-side human services


Tools available from the palette for client-side human services
Building a client-side human service
Implementing a BPD task using a client-side human service
Declaring variables
JavaScript API for client-side human service authoring
Calling another service from a client-side human service
Implementing exclusive gateways in client-side human services
Saving the state of a client-side human service during execution
Validating client-side coaches using client-side validation
Validating client-side coaches using server-side validation
Handling errors in client-side human services
Exposing client-side human services
Adding HTML meta tags to client-side human services
Enabling work to be postponed and resumed at run time
Navigation options for after service completion
Running and debugging client-side human services
Running client-side human services
Debugging client-side human services
Troubleshooting errors from running client-side human services
Keyboard accessibility for client-side human services
Adding nodes to client-side human services by using the keyboard
Heritage human service to client-side human service conversion
Building coaches
Validating coaches in heritage human services
Developing reusable coach views
Providing information about coach views
Defining coach view behavior
Improving coach view performance
Adding custom AMD modules
Accessing a child coach view
Configuring the design-time appearance of coach views
Adding variables to coach views
Defining the contents of coach views
Adding bidirectional language support
Setting the visibility of coach views
Calling Ajax services from coach views
Generating URLs of managed assets
Generating a unique ID for a coach view
Tips for debugging coach view lifecycle method inside client-side human services
Tips for debugging coach views in Process Portal
Enabling JavaScript debugging for coaches
Coach and coach view troubleshooting
Responsive settings for coach views
Coach and coach view examples
Example: creating a template
Example: wiring coaches in a human service

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

Example: creating a tabbed coach


Example: creating a Select control using custom HTML
Example: creating a Dojo button control
Example: creating a jQuery button control
Example: validating a coach in a client-side human service
Example: validating a coach in a heritage human service
Example: creating a coach that calls an Ajax service
Example: creating a coach for tablets and smartphones
Example: showing the label of a complex coach view
Building Heritage Coaches
Adding sections to a Heritage Coach and controlling the layout
Setting column widths in a Heritage Coach
Setting the number of columns in a Heritage Coach
Examples of building services with heritage coaches
Example: building an integration service with a Heritage Coach
Nesting the Integration service and mapping its variables
Building Heritage Coaches to collect input and display output
Building a heritage human service with heritage coaches
Example: Building a heritage human service with coaches
Building an Ajax service with Heritage Coaches
Configuring Heritage Coach controls
Populating a list with static data
Populating a list with dynamic data
Binding a complex data structure to a Table control
Populating a table control using an SQL query
Binding a variable to a custom HTML component
Making an input control a required field
Displaying a control based on the input value of another control
Displaying a control to a specific group
Changing the visibility of a Heritage coach control
Validating user input
Controlling field and other formatting in Heritage Coaches
Using pre-defined formats in Heritage Coach Controls
Using characters to apply custom numeric formatting
Adding custom format types
Using formatting with variables
Using formatting with language localization resources
Configuring a Hebrew or Islamic calendar
Aligning buttons in a Heritage Coach
Aligning check boxes and radio buttons in a Heritage Coach
Adding documents and reports to Heritage Coaches
Choosing the type of documents to attach to a Heritage Coach
Attaching IBM Business Process Manager documents to a Heritage Coach
Attaching ECM documents to a Heritage Coach
Embedding documents in a Heritage Coach
Embedding IBM Business Process Manager reports in a Heritage Coach
Customizing Heritage Coaches

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

How Heritage Coaches work


Adding custom images to a Heritage Coach
Overriding CSS styles for selected controls and fields
Specifying a custom CSS for a Heritage Coach
Specifying an XSL transform override for a Heritage Coach
Setting the length of input text fields
Enhancing interface layout using custom attributes
System services to implement conditional activities
Troubleshooting Heritage Coaches
Localizing process applications
Creating localization resources
Localizing user interfaces
Localizing coach view configuration options
Versioning process applications
Naming conventions
Naming conventions for Process Center server deployments
Naming conventions for Process Server deployments
Enabling document support
Working with IBM BPM documents
The IBM BPM document store
Inbound events for the IBM BPM document store
Inbound events for the IBM BPM content store
The IBM_BPM_Document document type
Creating IBM BPM documents
Updating IBM BPM documents
Working with the IBM_BPM_Document_Properties property
Writing to the IBM_BPM_Document_Properties property
Reading from the IBM_BPM_Document_Properties property
Updating the IBM_BPM_Document_Properties property
Specifying search criteria for the IBM_BPM_Document_Properties property
Working with IBM BPM documents in the Document List coach view
Limitations in working with IBM BPM documents
Integrating with Enterprise Content Management (ECM) systems
Adding an Enterprise Content Management server
Outbound interactions with Enterprise Content Management systems
Authentication scenarios
How to use Coach views to store or view documents
Configuring coach views for storing and viewing Enterprise Content
Management documents
Building a service that integrates with an ECM system or the IBM BPM
document store
Building a query for an Enterprise Content Management search operation
Working with a search result programmatically
Working with document content
Data mapping in Enterprise Content Management operations
Inbound events from Enterprise Content Management systems
Runtime behavior for inbound content events

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

Performing modeling tasks for inbound events


842
Subscribing to document and folder events: the end-to-end approach 844
Creating and configuring event subscriptions
848
Content event types
851
Creating attached services
855
Creating and configuring an undercover agent for a content event
856
Adding a content event to a BPD
856
The ECMContentEvent business object
858
Performing administrative tasks for inbound events
859
Creating an event handler for an Enterprise Content Management system
860
Using the event handler for FileNet Content Manager
862
Troubleshooting interactions with Enterprise Content Management systems
867
Integration considerations for ECM products
868
IBM FileNet Content Manager
869
IBM Content Manager
871
Alfresco Community
873
Microsoft SharePoint
875
Accessing the SharePoint CMIS provider from IBM BPM
877
Testing and debugging process applications
880
Visualizing process data
881
Visualize variables
883
Visualize tag groups
884
Keyboard shortcuts for data visualization
885
Running and debugging processes with the Inspector
887
Managing process instances
889
Restricting access to debugging for services
890
Stepping through a process
893
Debugging a process
895
Resolving errors
897
Inspector reference
898
Authentication during playback to handle changes in user identity
903
Globalization
904
Bidirectional support in IBM Business Process Manager
905
Applying bidirectional text layout transformation
906
Contextual support
908
Troubleshooting Process Designer and Process Center connectivity
909
Enabling error logging
911
Troubleshooting Process Designer and Process Center connectivity
913
Enabling error logging
913
SS9KLH_8.5.5/com.ibm.wbpm.ref.doc/topics/rcontext.html
913

Building process applications


In IBM Business Process Manager (BPM), process applications are the containers
for business processes and cases that are created in IBM Process Designer.
You can either create process applications in Process Center or export and import
process applications into Process Center. After a process application is created or
imported, it is stored and listed in the Process Center repository. You open process
applications in Process Designer where you can create and edit the business
process definitions (BPDs) or cases within those process applications.
For information about designing high-performing IBM Business Process Manager
solutions, see the following publications:
- For designing processes, see Chapter 5: Design considerations and patterns in
Business Process Management Design Guide: Using IBM Business Process
Manager.
- For best practices, see Chapter 2: Architecture best practices and Chapter 3:
Development best practices in IBM Business Process Manager V8.5 Performance
Tuning and Best Practices.
- For an overview of critical performance-related information, see IBM Business
Process Manager V8.5 Performance Tuning.
The following high-level diagram illustrates the basic tasks and activities that are
typically associated with building a process application.

- Business process management and case management


Business process management and case management are two approaches to
build a process. The type of business situation you are addressing determines
which approach you use.Case management functions are only available if you
have IBM BPM Advanced with the Basic Case Management feature installed.

- Getting started with IBM Process Designer


Process Designer is an easy-to-use graphics-oriented tool that enables you to
model and implement your business processes and easily demonstrate process
design and functionality during development efforts. This overview describes how
to begin using all of the tools that are available with Process Designer.
- Creating new process applications
When you create a new process application, you provide a name, acronym, and
optional description of the process application.
- Creating a process application from a WebSphere Business Modeler process
You can import business processes from WebSphere Business Modeler to
Process Designer.
- Creating processes in IBM Process Designer
Create processes in Process Designer that represent the processes in your
company. When you run your processes inside Process Designer, you can analyze
and simulate them in order to optimize your business activity.
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.
- 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.
- Business objects and variables
In Process Designer, variables capture the business data that is used by activities
in a business process definition or by steps in services such as integration services
or human services.
- Creating user interfaces for business processes
In IBM Business Process Manager, human services provide the logic and user
interface through which users can view and interact with business processes,
cases, data or process instances.
- Versioning process applications
Versioning provides the ability for the runtime environment to identify snapshots in
the lifecycle of a process application, and to be able to concurrently run multiple
snapshots on a process server.
- Enabling document support
- Testing and debugging process applications
- 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
2

layout transformation, and calendar support for Hebrew and Hijri.


- 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.

Business process management and


case management
Business process management and case management are two approaches to build
a process. The type of business situation you are addressing determines which
approach you use.Case management functions are only available if you have IBM
BPM Advanced with the Basic Case Management feature installed.
IBM Business Process Manager provides tools for the approaches to define and
then improve a process: business process management and case management.
Learn the differences so that you can select the best approach for your situation.
Consider two types of situations that a corporation faces. In the first situation, the
corporation wants more customers to use its credit card. In the second situation, the
corporation wants a process to handle calls about credit card billing problems. The
following sections describe the design and implementation you would likely use for
each situation.
- Designs for two types of business situations
- Building and running a business process
- Building and running a case
- Key differences between business process management and case management

Designs for two types of business situations


If you needed to get more customers to use your credit card, you might come up
with the following activities:
1. Define the type of customer you think might benefit from your credit card.
2. Use an application to search a database for potential candidates.
3. Use an application to email the candidates.
4. Review the candidates who responded to assess the effectiveness of the email
and determine patterns in the list of interested customers.
5. Use an application to check the credit rating of the respondents.
6. Use an application to mail the credit cards to candidates with good credit ratings.
The activities are in order and their order follows a predictable and repeatable
process. The process determines the sequence of events. It is a stable process that
likely remains unchanged over many years. A number of the actions can be
automated. In this scenario, a business process would most likely be your
implementation choice.
If you wanted to handle customers with credit card billing problems, you might come
up with the following unordered activities:
- Capture the complaint when someone called or sent an email.
- Get information about the customer.
- Get information about the vendor.
- Collect receipts and invoices to verify the complaint.
- Notify Customer Records if unusual information was found.
- Notify system administrators if the billing system caused problems.
- Notify Vendor Records if unusual information was found.
- Resolve the dispute.

The activities are unordered because the sequence of activities is unpredictable.


The events determine the order in which the activities in the process are followed.
People rather than programs interact to resolve the dispute. External documents are
needed for verification. In this scenario, a case would most likely be your
implementation choice.

Example of building and running a business process


The following business process might get more customers to use the corporation's
credit card. It is a wired process. You can see which activity follows the other. At run
time, the activities drive the events. For example, a worker defines the type of
customer that the worker is looking for and then starts the application to get the
candidates and email the candidates. Then, the worker waits until there is a list of
candidates to review based on the people who responded to the email. Finally, the
worker starts the credit check application. The credit check application is followed by
the application that mails out the credit cards. A worker at run time does not select
the next activity from a set of choices to choose what comes next; the next activity is
predetermined at development time.
The activities are in swimlanes that define the type of activity. The team lane is for
activities that people do and the system lane is for activities that programs do.
Programs automate and complete many activities. To implement these activities
with human services, subprocesses, services, and teams, you use the same set of
tools as you do to implement a case.

Example of building and running a case


The following case might handle credit card billing complaints. The activities are not
wired. No predetermined sequence is set at development time. A worker would likely
start by describing the complaint and finish by resolving the dispute. However,
whether the worker receives the customer information before the vendor information
would likely be determined by what the worker read in the complaint. The
information that is retrieved about the customer would determine whether the worker
would check with the people who handle the customer records. The information that
is retrieved about the vendor would determine whether the worker would check with
the people who handle vendor records. The information that is retrieved about either
the customer or the vendor might lead to investigating the computer billing system
for problems.
The activities are not in a swimlane that determines their type. Although the worker
5

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.

Key differences between business process management


and case management
Considering the previous scenarios, the following table summarizes the
characteristics of business process management and case management. Examining
these characteristics, you can select which type of process might best suit your
situation.
Table 1. Characteristics of business process management and case management
Business process management
You can define an ordered sequence of
activities that can be completed to solve
a business challenge.
The sequence of activities is stable and
seldom changes; that is, the process is
predicable and repeatable.
The process determines the events. The
first activity determines the first set of
events, which then leads to the next
activity and the next set of events. The
activities are wired to one another, which
determines the sequence.

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.

The activities are often programmatic. A


repeatable sequence, such as selecting
a set of potential credit card owners from
a database, can be automated.
External documents are not part of the
process.

People primarily determine the activities.


Handling a customer with a billing error is
done by a person who uses judgment to
determine the best resolution of this
particular case.
External documents play a key role. For
example, receipts provide a record for
how the problem that must be resolved
began.

Parent topic:Building process applications

Getting started with IBM Process Designer


Process Designer is an easy-to-use graphics-oriented tool that enables you to
model and implement your business processes and easily demonstrate process
design and functionality during development efforts. This overview describes how to
begin using all of the tools that are available with Process Designer.
For a high-level overview of the components of the Process Designer interface,
watch Getting Started with Process Designer version 8.5.5, available on YouTube
or in the IBM Education Assistant information center. A transcript of the video is
available.
- Process Designer interface
Before you start to build processes with IBM Process Designer, you must
understand the tools that are available in the Process Designer interface.
- Where to edit Process Designer artifacts
Learn where you can edit artifacts in IBM Process Designer.
- Process Designer tips and shortcuts
You can use several features in Process Designer to improve your efficiency.
- 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.
- Setting preferences
IBM Process Designer provides several settings to control the appearance and
functionality of the editors and interfaces that it includes.
Parent topic:Building process applications

Process Designer interface


Before you start to build processes with IBM Process Designer, you must
understand the tools that are available in the Process Designer interface.
The Process Designer interface provides the tools to model your processes in IBM
BPM. The following image and corresponding table describe the parts of the
Designer view that you interact with when modeling processes and implementing
the steps in those processes.

Table 1. Description of numbered areas on the Designer interface image


Number
1

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

Parent topic:Getting started with IBM Process Designer


Related information:
Known issues for translated IBM BPM components

10

Where you can graphically


model and configure your
process and design the
layout of coaches, human
services, and heritage
human services.
Provides BPMN elements
and variables that you can
use to model and configure
your process.
Where you can set
properties and
configuration options for
selected components in
your process.

Where to edit Process Designer artifacts


Learn where you can edit artifacts in IBM Process Designer.
In previous releases, you worked with artifacts in Process Designer on your desktop.
Now, you can work with artifacts that are in the Process Designer web editor and in
the Process Designer desktop editor. For example, to create process applications
that contain business process definitions (BPDs) and client-side human services,
you must use both the desktop editor and the web editor because there are some
Process Designer capabilities that you can access only on the web and some that
you can access only on your desktop.
Multiple users can work simultaneously on the same process applications and
artifacts in the two editors and changes happen automatically and seamlessly.
If you have Process Designer open on your desktop and you are working in the web
editor, you can edit certain artifacts in the desktop editor. When you click the
artifacts in the web editor, they open in the desktop editor so that you can edit them.
You can access the Process Designer web editor in the following ways:
- Open Process Designer desktop editor and then select an artifact that is editable
only on the web, such as a client-side human service, case type, or document
type. Case management functions are only available if you have IBM BPM
Advanced with the Basic Case Management feature installed.
- Open Process Designer desktop editor, select a coach view, and then right-click
and select Open in > Web Editor.
The following table lists which artifacts you can edit where (indicated with asterisks).
You can edit some artifacts in the desktop editor. You can edit other artifacts in the
web editor. The web editor opens in a web browser from Process Designer.
Table 1. Where you can edit Process Designer artifacts
Artifacts

Editable in the Process


Designer desktop editor
*

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.

Editable in the Process


Designer web editor

*
*

11

coach viewNote: To use


responsive features in
coach views, for example
to have the runtime
behavior respond to
different screen size
environments, you must
edit coach views in the
web editor.
client-side human service
decision service
design file
document typeNote:Case
management functions are
only available if you have
IBM BPM Advanced with
the Basic Case
Management feature
installed.
event subscription
external implementation
exposed process value
General System service
heritage human service
historical analysis scenario
IBM Case Manager
Integration service
Integration service
key performance indicator
(KPI)
localization resource
process application setting
server file
service-level agreement
simulation analysis
scenario
teamNote: To define a
team using a filter or
retrieval service, you need
to edit this artifact in the
Process Designer desktop
editor.
timing interval
tracking group
undercover agent
user attribute definition
web file

*
*
*
*

*
*
*
*
*
*
*
*
*
*
*
*
*
*

*
*
*
*
*

12

web service

Parent topic:Getting started with IBM Process Designer

13

Process Designer

tips and shortcuts

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.

Process Designer preferences


The following steps describe how to access the preference settings and the
following table describes the options that are available:
1. Select File > Preferences from the main menu.
2. Click the IBM BPM entry to display the available options.
3. Click the option that you want. For example, to set the user name for Blueworks
Live process subscriptions, click the Blueworks Live option.
Table 1. Options for IBM Process Designer preferences
Option
Blueworks Live

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

Manage the passwords that are


stored when running tasks from
the Inspector.
Select the web browser to use
when web pages are opened
from IBM Process Designer. If
you do not see a particular
external web browser as an
option, click New to add it.

Process Center Console preferences


To set the locale for IBM Process Center Console and Process Designer, access
the Process Center Console by opening your web browser to the following location:
http://[host_name]:[port]/ProcessCenter. Click Preferences in the upper
right corner and choose the language that you want from the list. When you change
the locale, you must exit and then restart IBM Process Designer for the change to
take effect. (When you are accessing Process Center Console from a browser, you
can log out and then log back in for the change to take effect.)
The locale preference that you selected applies to the user who logs in. Each IBM
Business Process Manager interface that is started by the same user in the same
environment uses this preference setting.

Process Designer XML configuration settings


The IBM BPM settings related to Process Designer are transferred through the
network from Process Center to Process Designer as properties of the
AuthoringEnvironmentConfig configuration object every time Process Designer is
launched. These properties affect the connections created between Process
Designer and Process Center. Based on your business requirements, you might
want to change the properties of Process Designer.
For IBM BPM XML configuration settings that are related to Process Designer, see
the following table that contains properties and explains how to set the properties.
The AuthoringEnvironmentConfig object contains the following properties:
Name
Images Prefix

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

The Portal Prefix endpoint


maps to the
AE_PORTAL_PREFIX
scenario key, which
configures the URLs that
are used in the Process
Designer authoring
environment to reach
Process Portal.
Repository Prefix
The Repository Prefix
endpoint maps to the
AE_REPOSITORY_PREFI
X scenario key, which
configures the URLs that
are used in the Process
Designer authoring
environment to reach the
repository.
Servlet Prefix
The Servlet Prefix endpoint
maps to the
AE_SERVLET_PREFIX
scenario key, which
configures the URLs that
are used in the Process
Designer. This scenario
must specify an absolute
URL by setting the url
property.
Social Bus WebApp Prefix The Social Bus WebApp
Prefix endpoint maps to
the
AE_SOCIALBUS_WEBAP
P_PREFIX scenario key,
which configures the URLs
that are used in the
Process Designer
authoring environment to
reach the social bus web
application.
Web API Prefix
The Web API Prefix
endpoint maps to the
AE_WEBAPI_PREFIX
scenario key, which
configures the URLs that
are used in the Process
Designer authoring
environment to reach the
web API.

19

REST Gateway Prefix

The REST Gateway Prefix


endpoint maps to the
AE_REST_GATEWAY_CR
_PREFIX scenario key,
which configures the URL
that is used in the Process
Designer authoring
environment to reach the
Process Center REST
Gateway.
Web PD Prefix
The Web PD Prefix
endpoint maps to the
AE_WEB_PD_PREFIX
scenario key, which
configures the URL that is
used in the Process
Designer authoring
environment to launch the
web editor.
Webviewer WebApp Prefix The Webviewer WebApp
Prefix specifies the
endpoint of the web
application contained in the
webviewer.war file.The
host and port number of
the URL can be
customized by setting the
IBM BPM virtual host.
The context root of the
URL can be customized by
adding a prefix before the
context root.
BPM Asset Prefix
The BPM Asset Prefix
specifies the endpoint of
the web application
contained in the
bpmasset.war file. The
host and port number of
the URL can be
customized by setting the
IBM BPM virtual host.
The context root of the
URL can be customized by
adding a prefix before the
context root.

20

Information on setting the


IBM BPM virtual host is
found in the topic
Configuring endpoints to
match your topology.
For information about
setting the context root
prefix, see the topic
BPMConfig command-line
utility.

Process Portal Prefix

HTTP Protocol Only

The Process Portal Prefix


specifies the endpoint of
the web application
contained in the processportal.war file. The host
and port number of the
URL can be customized by
setting the IBM BPM virtual
host.
The context root of the
URL can be customized by
adding a prefix before the
context root. For example,
/prefix/ProcessPortal.
If this attribute is set (which
is the default),
communication between
Process Designer and
Process Center is limited
to using HTTP or HTTPS
protocols instead of RMI
with JMS.
Note that if the attribute is
not set, HTTP or HTTPS
communication still occurs
between some Process
Designer components and
Process Center, but not
exclusively.

21

Information on setting the


httpProtocolOnly

attribute is found in the


topic Configuring the
httpProtocolOnly property
for Process Designer.

Suppress Redirect URL


Password

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

Information on setting the


suppressRedirectUrlPas
swd attribute is found in the

topic Installing IBM


Process Designer.

suppressRedirectUrlPas
swd option stops the

password from being


included in the URL to
improve security. Note:
When you use the
suppressRedirectUrlPas
swd option, you only need

Formatting Templates

to log into the browser the


first time that you open a
web editable artifact or run
a playback in Process
Designer. This option only
applies to Process
Designer and can be
turned on and off as
needed.
Specifies the predefined
character formats for text
controls or specifies the
creation of additional
formats. The data type is
FormattingTemplatesConfi
g.<authoring-environment

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

These properties are all


configured using IBM BPM
configuration XML files.
For information about
setting the properties, see
the topic Changing IBM
Process Server properties
in 100Custom.xml.

Inspector

This property specifies


inspector configuration.
The data type is
InspectorConfig.<authoringenvironment merge="mergeChildren">
<inspector>
<target-servers>
<type></type>
<name></name>
<default-action-policy>
<action>
<type></type>
<role>role1</role>
<role>role2</role>
</action>
</default-action-policy>
</target-servers>
</inspector>
</authoring-environment>

Library Event Stream


Manager

The data type is


SequencedStateDeltaMan
agerConfig.<authoring-environment

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

The data type is


MimeTypesConfig.<authoring-

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>

Repository Broken Ping


Time

Specify an integer value.


The default value is 15000
if the value is set to 0 or a
value is not
specified.<authoring-environment
merge="mergeChildren">
<repository-broken-ping-time
merge="replace">
</repository-broken-ping-time>
</authoring-environment>

Repository Max Wait


During Shutdown

Specify an integer value.


The default value is 3000 if
the value is set to 0 or a
value is not
specified.<authoring-environment
merge="mergeChildren">
<repository-max-wait-during-shutdown
merge="replace">
</repository-max-wait-during-shutdown>
</authoring-environment>

23

Repository Ping Delay

Specify an integer value.


The default value is 15000
if the value is set to 0 or a
value is not
specified.<authoring-environment

merge="mergeChildren">
<repository-ping-delay merge="replace">
</repository-ping-delay>
</authoring-environment>

Repository Slow Ping Time Specify an integer value.


The default value is 7500 if
the value is set to 0 or a
value is not
specified.<authoring-environment
merge="mergeChildren">
<repository-slow-ping-time
merge="replace">
</repository-slow-ping-time>
</authoring-environment>

Add Redirect URL


Credentials

Specifies whether the


credentials are permitted to
be passed in IBM Business
Process Manager URLs.
For example, a service can
be started directly from
IBM Process Designer
without presenting a login
screen. The default value
is true.<authoring-environment
merge="mergeChildren">
<add-redirect-url-credentials
merge="replace">true
</add-redirect-url-credentials>
</authoring-environment>

Deploy Snapshot Using


HTTPS

Specifies whether the


Process Center Server
uses HTTPS to deploy
process applications and
toolkits to process servers.
If the property is set to the
default value of true and
all process servers are
secure, then
communication from
Process Center to Process
Server will work with HTTP
Secure (HTTPS) or HTTP
over SSL. However, if you
have a mix of secure and
non-secure servers,
Process Center can only
communicate with Process
Servers that are configured
to work with this mixed
configuration.<authoringenvironment merge="mergeChildren">
<deploy-snapshot-using-https
merge="replace">true
</deploy-snapshot-using-https>
</authoring-environment>

24

Encode Redirect URL


Credentials

Specifies whether the


credentials that are passed
in an IBM Business
Process Manager URL that
implements redirectlogin.jsp are encoded.
For example, you can
encode credentials in a
URL that is used to start a
service directly from IBM
Process Designer. By
default, this property is set
to true, which specifies
that the credentials passed
in an IBM BPM URL are
encoded. If you change the
setting to false, the URL
is composed with
credentials in plain
text.<authoring-environment
merge="mergeChildren">
<encode-redirect-url-credentials
merge="replace">true
</encode-redirect-url-credentials>
</authoring-environment>

Parent topic:Getting started with IBM Process Designer

25

Creating new process applications


When you create a new process application, you provide a name, acronym, and
optional description of the process application.

About this task


You create new process applications in Process Center. You can access the
Process Center console in the following ways:
- From entering the remote Process Center URL (for example
https://servername:9080/ProcessCenter/login) into a web browser.
- By starting the Process Designer desktop editor.
Tip: If you are creating processes in your process application, use the Process
Designer desktop editor. If you are building cases in your process application, use
the remote Process Center URL.

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.

Parent topic:Building process applications

27

Creating a process application from a WebSphere


Business Modeler process
You can import business processes from WebSphere Business Modeler to Process
Designer.

About this task


You can do this by importing the BPMN models that you exported earlier from
WebSphere Business Modeler BPMN 2.0 file archive (.zip) files. You can import
your models into the IBM Process Center. You can then use the IBM Process
Designer to open the resulting Process App or Toolkit, if you want to see the details
of what was imported or to make changes to the imported models.

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

Next Steps after importing BPMN Models


Procedure
1. Open the Process App or Toolkit that you created
2. Open every single generated artifact and ensure that its contents appear as
expected.
3. Replace any of the default generated logic with the intended logic wherever
necessary.
4. Complete the following steps for each of the following artifact:Services: Enter the
service flow details
A. Human services: Customize the default generated coach
B. Rule services: Enter the rule details
Teams: Specify the team members Processes:
A. Private Variables: Provide default values for any variables that are not
initialized.
B. XOR and IOR Gateways: Enter the conditional logic
C. Javascript Activities: Enter the javascript logic
D. Adjust the process layout to minimize connection crossing.
5. Check for validation messages and fix them as necessary.

29

Creating processes in IBM Process Designer


Create processes in Process Designer that represent the processes in your
company. When you run your processes inside Process Designer, you can analyze
and simulate them in order to optimize your business activity.
The following diagram illustrates the main tasks and activities that are associated
with creating processes.

- 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

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.

Before you begin


To perform this task, you must be in the IBM Process Designer desktop editor.
Ensure that you have access to a process application in the Process Center
repository.

About this task


Process modeling captures the ordered sequence of activities within a process
along with supporting information from end to end. In process modeling, the
business process is framed in a BPD to reflect the activities, the roles that conduct
those activities, conditional branching, and the sequence of the workflow between
the activities.Tip: When you create a BPD, use the Business Process Model and
Notation (BPMN) standards so that everyone who is involved with the process can
interpret and understand the process model. BPMN also compacts your BPD by
using symbols to represent ideas.
Tip: Create BPDs in a process application, not in a toolkit. A BPD in a toolkit can
result in process instances running inside the toolkit. A process instance running in a
toolkit cannot be migrated.
A business process definition needs to include a lane for each system or group of
users who participates in a process. A lane can be a participant lane or a system
lane. However, you can create a BPD that groups the activities of a group and a
system into a single lane if that is your preference.
You can designate any specific person or group to be responsible for the activities in
a participant lane. Each lane that you create is assigned to the All Users group by
default. You can use this default group for running and testing your BPD in the
Inspector. The All Users group includes all users who are members of the
tw_allusers security group, which is a special security group that automatically
includes all users in the system.
A system lane contains activities handled by a specific IBM Process Center system.
Each activity needs an implementation, which defines the activity and sets the
properties for the task. During implementation, a developer creates a service or
writes the JavaScript necessary to complete the activities in a system lane.
For each BPD that you create, you need to declare variables to capture the
business data that is passed from activity to activity in your process.
You can also add events to a BPD. Events in IBM BPM can be triggered by a due
date passing, an exception, or a message arriving. The trigger that you want
determines the type of event you choose to implement.

Procedure

34

1. Open the Process Designer desktop editor.


2. Open a process application in the Designer view.
3. Click the plus sign next to Processes and select Business Process Definition
from the list and complete the fields in the New Business Process Definition
window.
4. Design your process by dragging BPMN elements from the palette onto the
diagram area.
5. To specify the details for an element, select the element in the diagram and edit
its properties in the Properties view.
- Adding lanes to a BPD
A Business Process Definition (BPD) can include a lane for each system or team
of users who participate in a process. A lane is the container for all the activities to
be carried out by a specific team or by a system.
- Adding activities to a BPD
In a business process definition (BPD), you can include activities that represent
logical work that a specific team or a system completes.
- Adding events to a BPD
When modeling a process, you might want to model events that can occur at the
beginning, during, or at the end of a runtime process (as opposed to activities that
are carried out by participants in the process).
- Modeling process execution paths by using sequence flows
Use sequence flows to connect activities and other modeling constructs to
establish the process flow.
- Converging and diverging flows
Gateways control the divergence and convergence of a sequence flow,
determining branching and merging of the paths that a runtime process or case
instance can take.
- Example gateways
The following samples illustrate how to model several types of gateways.
- Implementing activities in a BPD
Choose the implementation for each activity in your BPD and set the required
properties.
- Assigning teams to BPDs and lanes
Assign teams of users that can start activities, and teams that can work on
activities in Process Portal. You can assign a team of instance owners for a BPD,
or you can assign teams for individual activities and lanes.
- Assigning teams to BPD activities
For any activity with a service implementation, you can designate the users who
receive the runtime task by using the Assignments page in the properties for that
activity.
- Configuring conditional activities
You can use conditional activities to model steps which are either skipped or
completed during run time based on the values of specific process variables. The
decision to skip or complete a conditional activity can be made by the runtime user
or programmatically, based on scripted rules.
- Creating an unstructured (ad hoc) activity
An ad hoc activity has no input wires and is started as required by knowledge
35

workers or according to predefined preconditions, rather than by a predefined


process flow. Such activities can be required or optional, and they can be defined
as repeatable or to run at most once. Knowledge workers can start unstructured
activities from the Activities section in the Process Instance details page in Process
Portal.
- 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.
- Creating a user attribute definition
You can associate unique capabilities or qualities with one or more users by
creating user attribute definitions.
- Validating processes
Use validation functions to refine process definitions as you build them.
- Task types
Learn more about the task types that are available when modeling with IBM
Process Designer.
- Creating user interfaces for a BPD
Create customized user interfaces that a user sees for the process instance in
Process Portal.
Parent topic:Modeling processes
Related information:
Business process definitions (BPDs)
Modeling events
Declaring and passing variables
Service types

36

Adding lanes to a BPD


A Business Process Definition (BPD) can include a lane for each system or team of
users who participate in a process. A lane is the container for all the activities to be
carried out by a specific team or by a system.

Before you begin


To perform this task, you must be in the IBM Process Designer desktop editor.

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

Adding activities to a BPD


In a business process definition (BPD), you can include activities that represent
logical work that a specific team or a system completes.

Before you begin


To perform this task, you must be in the IBM Process Designer desktop editor.

About this task


When you add activities, follow these guidelines:
- Ensure that activities represent logical units of work that are assigned to a
participant of a process.
- Make multiple concurrent workflow steps that are assigned to one responsible role
into one activity or task.
- Use verb-noun statements to label activities, such as Submit job requisition.
- Apply a top-down, left-to-right flow to your BPD so that it is easier to read.

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

Adding events to a BPD


When modeling a process, you might want to model events that can occur at the
beginning, during, or at the end of a runtime process (as opposed to activities that
are carried out by participants in the process).

Before you begin


To perform this task, you must be in the IBM Process Designer desktop editor.

About this task


An example of an event is a message received from an external system. You can
specify the trigger type of an event and represent the event with a meaningful icon in
your process diagram.
Events in IBM BPM can be triggered by the passing of a due date, an exception, or
the arrival of a message. The trigger determines the type of event that you choose
to implement. For information about available event types and their triggers, see
Modeling events.
You can attach intermediate events (timer, message, and error events) to activities
in your business process definitions (BPDs) to create boundary events or you can
include intermediate events in the process flow by using sequence lines. Other
events must be part of the process flow.

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

Modeling process execution paths by using


sequence flows
Use sequence flows to connect activities and other modeling constructs to establish
the process flow.

Before you begin


To perform this task, you must be in the IBM Process Designer desktop editor.

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

Converging and diverging flows


Gateways control the divergence and convergence of a sequence flow, determining
branching and merging of the paths that a runtime process or case instance can
take.

About this task


You can think of inclusive and exclusive gateways as questions that are asked at a
particular point in the flow. The question has a defined set of alternative answers,
which act as gates. The process or case cannot proceed until a valid answer is
provided. You can model questions by using JavaScript conditions, which are
evaluated before the flow is allowed to proceed.Note:Case management functions
are only available if you have IBM BPM Advanced with the Basic Case Management
feature installed.
You can model the following types of gateways in your process or service flow
diagram:
Table 1. Types of gateways that can be modeled in process diagrams
Component icon

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

Use to model a point in the


process or service flow
execution where only one
of several paths can be
followed, depending on a
condition, or to model a
point in process execution
when the token for one of
several incoming paths is
passed through the
gateway. Note: The
exclusive gateways are the
only gateways that can be
implemented in human
services. For more
information, see
Implementing exclusive
gateways in client-side
human services.
Use to model a point in the
process execution where
only one of several paths
can be followed,
depending on events that
occur. A specific event,
such as the receipt of a
message or timer event,
determines the path to be
taken. An event gateway
must be modeled a certain
way as described in
Modeling event gateways.

Restriction: In human services, support for gateway implementation is provided for


exclusive gateways only.
Be aware of the following when using gateways:
- After you drag a gateway from the palette to your diagram, you can choose any of
the available gateway types.
- When you model inclusive and exclusive gateways, if all conditions evaluate to
false, the process follows the default sequence flow. The default sequence flow is
the first sequence flow that you create from the gateway to a following activity, but
you can change the default sequence flow at any time, as described in the
following procedure.
For more information about implementing inclusive and exclusive gateways, see
Example gateways.
To add gateways to a process or human service diagram:

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.

6. Configure the implementation for the gateway.


A. For inclusive and exclusive gateways, click the Implementation tab. For each
outgoing sequence line, a condition (in JavaScript) is required that controls
whether the path is followed. (For more information about the types of
conditions that you can define, see Example gateways.) Ensure that the
sequence flow shown as the Default Line is the one that you want the
process or service flow to follow if all conditions evaluate to false. If not,
reorder the lines until the one that you want is designated the default. Note: A
default sequence flow does not have a condition.
B. For event gateways, see Modeling event gateways.
7. Click Save in the main toolbar.
Parent topic:Creating a business process definition (BPD)

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.

Sample exclusive gateways


Use an exclusive gateway in a BPD or in a human service when you model a point
in the flow in which only one of several paths can be followed. JavaScript conditions
that you define for the sequence flows that emerge from the gateway determine
which path is to be followed by the flow.
In the Implementation properties, decisions are evaluated from top to bottom. The
flow follows the first condition that evaluates to true. If all conditions evaluate to
false, the flow follows the default sequence flow, which does not have a condition.
- Sample exclusive gateway in a BPD
- For example, you might have two exclusive gateways in a BPD diagram.Note:
You can access the HR Open New Position BPD in the Hiring Sample process
application or see Hiring Sample tutorial: Add event gateways and Hiring
tutorial: Implement gateways in the Hiring tutorial section.
In the sample and tutorial, the first gateway, named Need GM Approval?,
determines which path to follow based on whether the submitted job requisition
requires approval. To see how this works, click the gateway in the BPD diagram
and then click the Implementation option in the properties. The approval
options are then shown under the Decisions section.

45

Remember: To enable the advanced editing feature in your preferences, click


File > Preferences, expand IBM BPM > Capabilities > IBM BPM Advanced
Features, and then select Advanced Editors.

The Approval required path is followed to the Approve/reject


requisition activity only when the
tw.local.currentPosition.positionType variable is equal to "New". This
logic ensures that those requisitions from Hiring Managers for new headcount
are approved by General Managers before HR processing. If a position is not
new, the process follows the default path to the Find job candidates activity.
Notice in the BPD diagram that the default path is marked with a forward slash
(/).
The second gateway, named GM Approved?, determines which path to follow
based on whether a new position is approved. To see how this works, click the
GM Approved? gateway in the BPD diagram to select it, and then click the
Implementation option in the properties. The approval information is then
shown under the Decisions section.
The Approved --> proceed to HR path is followed to the Find job
candidates activity only when the tw.local.requisition.gmApproval
variable is equal to "Approved". This logic ensures that those requisitions that
require approval are approved before HR processing. If a requisition is not
approved, the process follows the default path (Rejected path) to the Notify
hiring manager activity.
- Sample exclusive gateway in a human service
- The following example shows the implementation of an exclusive gateway in a
human service. To model the exclusive gateway in the service flow, JavaScript
conditions that evaluate to true or false are defined in the implementation
46

properties of the gateway, under Decisions. A default sequence path is also


specified in the Default Flow list, with no JavaScript condition associated with
it. The flow follows the first condition that evaluates to true or, if all conditions
evaluate to false, it follows the default sequence path.

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.

Sample inclusive gateway


Use an inclusive gateway in a BPD when you need to split or diverge the process
along more than one path, and you want to follow one or more available paths
based on conditions that you establish.
Note: Inclusive gateways can follow a maximum of n-1 paths. So, if you model a
conditional split with three paths, the process can follow two of those paths.
Restriction: Support for implementing inclusive gateways in human services is not
provided.
For example, suppose that you want to model a process where the steps are
different based on whether the customer type is new or existing. For new customers,
you want activities 1 and 2 to be completed. For existing customers, only activity 3 is
needed. You can use an inclusive gateway (split) for this type of process so that two
activities are set for new customers and a third activity is set for existing customers.

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.

Parent topic:Creating a business process definition (BPD)

48

Implementing activities in a BPD


Choose the implementation for each activity in your BPD and set the required
properties.

Before you begin


To perform this task, you must be in the IBM Process Designer desktop editor.

About this task


The following table lists the options available when you choose the implementation
for an activity and provides a link to detailed information and procedures. To learn
more about the types of tasks that are available, see Task types.Table 1.
Implementation options available for activities in process diagrams
Implementation option
User Task

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

Select this option when


you want a decision or
condition in a business rule
to determine which
process implementation is
started. For example, if you
want Process Designer to
implement an activity when
a condition evaluates to
true, choose Decision
Task and select or create
a decision service to
implement the task.
Choose this option if you
plan to create a script to
implement an activity. A
Script activity runs a
Java script.
Use this option to
encapsulate 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. Therefore,
use a subprocess for those
implementations that are
limited to a single business
process definition (BPD).
You can implement an
activity by using a linked
process. Linked processes
encapsulate logically
related steps within a
process while retaining the
high-level view of the
parent process. Linked
processes differ from
subprocesses because
they can be accessed and
instantiated from
processes other than a
single parent process.

50

Service types

Using JavaScript variables


and objects inside Process
Designer
Subprocess types

Working with linked


processes

Event Subprocess

None

Use this specialized


Modeling event
subprocess to model
subprocesses
event-handling logic for a
process or subprocess. It
is triggered upon
occurrence of a configured
start event, and it is not
connected to other steps
through a sequence flow. It
has access to the business
objects (variables) of its
parent process, and can
encapsulate steps that use
those variables. When
triggered, an event
subprocess can either
interrupt the execution of
its parent or can run in
parallel.
Select this option if you are
not ready to associate an
implementation. Use this
option to create a
temporary placeholder
activity in your process
diagram until an
implementation is
available. If you run a
process that includes an
activity with this option
selected, the task
completes immediately
after it starts.

Tip: To learn how to make an activity conditional, see "Configuring conditional


activities".

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

option from the list: Minutes, Hours, or Days.


C. Under Schedule, select an option from the list. 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. You can leave the
Schedule, Timezone, and Holiday Schedule fields set to (use default). If
you do, the work schedule that is specified for the BPD is used. For more
information, see "Setting the due date and work schedule for a BPD".
D. Under Timezone, 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.
E. Under Holiday Schedule, leave the setting at (use default) as described in
the preceding note, or click JS 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 String-generated JavaScript) or a JavaScript
that returns a TWHolidaySchedule variable. If you use a String, IBM BPM
looks up the Holiday Schedule by name according to those rules. If you use a
TWHolidaySchedule variable, IBM BPM assumes that the holiday schedule is
appropriately specified. (Go to the System Data toolkit and open the
TWHolidaySchedule variable to view its parameters.)
9. (User Tasks only) In the Processing Behavior section, select Automatically
flow to next task if you want the next task in the sequence to run automatically.
- Implementing a BPD activity as a human service
If an activity in the business process definition (BPD) is to be completed by a user,
you can implement the activity as a client-side human service or a heritage human
service.
- Creating loops for a BPD activity
When you want the runtime task that results from a BPD activity to be run more
than once, you can create a loop. You can create simple loops and multi-instance
loops in IBM Business Process Manager.
Parent topic:Creating a business process definition (BPD)
Related tasks:
Setting the work schedule for a BPD
Automatically starting the user's next task
Related information:
Service types
Configuring conditional activities

53

Implementing a BPD activity as a human service


If an activity in the business process definition (BPD) is to be completed by a user,
you can implement the activity as a client-side human service or a heritage human
service.

Before you begin


To perform this task, you must be in the IBM Process Designer desktop editor.

About this task


To implement the activity as a service:

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.

Parent topic:Implementing activities in a BPD


Related information:
Client-side human services
Difference between client-side human services and heritage human services

54

Creating loops for a BPD activity


When you want the runtime task that results from a BPD activity to be run more than
once, you can create a loop. You can create simple loops and multi-instance loops
in IBM Business Process Manager.
Prerequisite: To create loops, you must be in the IBM Process Designer desktop
editor.
IBM Business Process Manager provides several ways to create and implement
loops. For example, you can include a script component in a service that iteratively
processes records that you retrieve from a database until all records are processed.
Since you can include JavaScript throughout your implementations, you can easily
develop the logic required to repeat an action until a certain condition is true.
In addition to implementing loops with scripts, the activities that you add to your
BPDs can be configured for simple and multi-instance loops, as described in the
following table. When you want the runtime task that results from an activity to be
run more than once, you can configure loop behavior for that activity.
Table 1. Loop types available for loop configuration
Loop type
Simple loop

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.)

- Configuring a BPD activity for simple loops


Follow these steps to configure a BPD activity for simple loops.
- Configuring a BPD activity for multi-instance loops
Using multi-instance loops, you can dynamically run multiple unique instances of
the same activity sequentially or in parallel. When you run a BPD activity that is
configured for multi-instance loops, a unique token is created for each instance of
the activity.
Parent topic:Implementing activities in a BPD

55

56

Configuring a BPD activity for simple loops


Follow these steps to configure a BPD activity for simple loops.

Before you begin


To perform this task, you must be in the IBM Process Designer desktop editor.
Restriction: Ad hoc start events are not supported in simple loop activities. If you
are using looping, do not define ad hoc actions for Process Portal users to start.

About this task


When you model an 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.

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

shown in the following image:


Parent topic:Creating loops for a BPD activity

57

Configuring a BPD activity for multi-instance loops


Using multi-instance loops, you can dynamically run multiple unique instances of the
same activity sequentially or in parallel. When you run a BPD activity that is
configured for multi-instance loops, a unique token is created for each instance of
the activity.

Before you begin


To perform this task, you must be in the IBM Process Designer desktop editor.
Restriction: Ad hoc start events are not supported in multi-instance loop activities.
If you are using looping, do not define ad hoc actions for Process Portal users to
start.

Procedure
1.
2.
3.
4.
5.
6.

Open the Process Designer desktop editor.


Open a process application that contains a BPD.
In the BPD diagram, select the activity that you want to configure.
In the properties, select General.
Under Behavior, select Multi-instance Loop from the Loop Type list.
Under Multi-instance Loop, type a value in the Start Quantity box. This value
sets the number of instances that are created at run time. To specify a variable
that can be used for this setting, click the variable icon to select it or type the
variable name into the Start Quantity box. Tip: For information about how to
associate each loop activity instance with a specific item in a list, see
Associating loop activity instances with different items.
7. From the Ordering list, select one of the following options:
Option
Run Sequential

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

Conditional Wait (Complex)

Looping continues until the


condition that you specify in the
following step is met.
9. For complex flow conditions, type the JavaScript to implement that condition in
the Complex Flow Condition box.
10. If you want active instances of the activity to be canceled when the preceding
condition is met, select Cancel Remaining Instances.The runtime behavior of a
multi-instance loop depends on how its task is implemented. The behavior is
different when the task content contains server scripts only and when it also
includes services. For example, a loop with Ordering selected to Run in
Parallel, with a valid complex flow condition, and Cancel Remaining Instance
set to true, runs as follows:
- Loop content contains server scripts only: If you specify only server scripts in
the multi-instance loop task content, the various instances of the loop run
sequentially. Therefore, all instances run in sequence, they all run to their end,
and at the end of all task instances the exit conditions are verified, again
sequentially.
- Loop content contains Human, Decision, or System services: If the loop task
content contains a Human, Decision, or System Service, then the tasks
instantiate in parallel within their own thread. In the example of the System
service, if an exit condition is set, upon completion of the System service task,
the result is given back to the multi-instance loop. Then, the condition is
evaluated and the multi-instance loop task completes, which ends all other still
running loop instances.
11. Save your changes.
Parent topic:Creating loops for a BPD activity

Associating loop activity instances with different items


About this task
You can configure activity instances in multi-instance loops so that each instance
corresponds to one specific item in a list. For example, if you have five instances of
an activity and five orders in a list, you might want to associate each instance with
an order in the list. To set up the activity instance-item association, the following key
settings are required:
- As a prerequisite, you must already have defined a private variable that holds the
list of items that you want to iterate through, for example, tw.local.ListofItems. This
variable is used in the built-in tw.local.ListofItems.listLength JavaScript
function, where .listLength calculates the length of the item list.
- You associate each activity instance with a specific item in the list by using the
tw.local.ListofItems[tw.system.step.counter] JavaScript, where
[tw.system.step.counter] specifies which item to be retrieved from the list.

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

Assigning teams to BPDs and lanes


Assign teams of users that can start activities, and teams that can work on activities
in Process Portal. You can assign a team of instance owners for a BPD, or you can
assign teams for individual activities and lanes.

Before you begin


To perform this task, you must start the Process Designer desktop editor. For
information about how to create a team, see Creating a team.

About this task


You can assign teams to activities that are implemented as user tasks (including ad
hoc activities), to lanes, and as instance owners in the Overview page of the BPD
editor. Teams that are assigned to activities and lanes determine which users can
work on tasks in Process Portal. If a team is assigned to a user task activity,
members of that team can work on that task in Process Portal. If a team is assigned
to a lane, members of that team can work on all the tasks that are part of that lane. If
both a user task activity and the lane in which it is contained have teams that
assigned to them, the team that is assigned to the activity is used.
If a user task implements an ad hoc activity, members of the team that is assigned
to the lane or members of a task-specific team can work on the task. The instance
owners team and lane teams are authorized to perform actions that are related to an
ad hoc activity, such as starting a manual activity.
Members of the instance owners team can start the task in Process Portal, and can
start, disable, and enable ad hoc activities in the BPD. For instances that they own,
they can reassign user tasks, set their due dates and the priority of tasks.

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

To assign teams to activities, see Assigning teams to BPD activities


1. Click Save in the main toolbar.
Parent topic:Creating a business process definition (BPD)

62

Assigning teams to BPD activities


For any activity with a service implementation, you can designate the users who
receive the runtime task by using the Assignments page in the properties for that
activity.

Before you begin


To perform this task, you must be in the IBM Process Designer desktop editor.

About this task


Note: Assignment options are available only for those activities with a BPM service
implementation.

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

Routing Policy (Deprecated)


List of Users (Deprecated)

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)

Assigns the runtime task according to


the JavaScript expression that you
provide in the corresponding field. To
select one or more variables for your
expression, click the variable selection
icon next to the field. The JavaScript
expression produces results such as
USER:<user_name> or
ROLE:<group_name>, where user_name
is the name of an IBM BPM user (such
as author) and group_name is the
name of an IBM BPM security group
(such as tw_authors).Note: Complex
JavaScript expressions can be typed in
or pasted into the Expression field and
can be customized as required. More
valid expressions can be chained
together to produce a complex
JavaScript expression, for example
tw.local.isWeekendCrew?"ROLE:Week
endManagers":"ROLE:Managers".

Important: To show up in the Team Performance dashboard, tasks must be


assigned to a Team or a team Lane. Tasks that are assigned to the deprecated
options are not displayed on the Team Performance dashboard.
6. Optional: From the Experts Team list, select the team that you want to associate
with the selected activity.
7. If you selected Assign ToTeam you must assign a team.
A. To define a new team, click New, provide a name, and complete the team
properties. For more information about the team properties, see Creating a
team.
B. If you want to select an existing team, click Select, then choose a team from
the list.
C. If you want to specify a fixed team name or a team that is not defined yet, enter
the name as a literal value, for example, damageAssessors.
D. If you want the team to be selected by the value of a local or environment
variable, specify the name of the variable, for example,
tw.local.dynamicTeamName.
8. Optional: If you selected Assign ToTeam or Assign ToLane the Team Filter
Service section is displayed. If you want to use a team filter service to eliminate
certain users before the user distribution is applied, complete the following steps.
A. To assign a Team Filter Service, either click Select to select an existing team
filter service or click New to define a new one. If you select New, perform
Setting up a team filter service.
B. If the team filter service that you selected or defined requires parameters from
the application, a Team Filter Service Input Mapping section is displayed.
For each required service variable, enter the corresponding process variable
name, for example tw.local.estimatedClaimAmount or tw.system.user.id
.

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.

- Assigning an activity to a dynamically retrieved team


If you do not want to assign an activity to a static team, you can define a team
retrieval service that dynamically returns a set of users and managers.
- Setting up a routing policy (deprecated)
One of the options when routing the runtime tasks that are generated by activities,
is to establish a routing policy.
- Defining rules with a routing policy (deprecated)
When you establish a Routing Policy for a BPD activity, you establish rules to
determine the recipients of the activity as a runtime task.
- Assigning an activity to an ad hoc list of users (deprecated)
An activity can be assigned to an ad hoc user list if the user group is defined
dynamically when a business process definition (BPD) instance is running.
Parent topic:Creating a business process definition (BPD)

65

Assigning an activity to a dynamically retrieved


team
If you do not want to assign an activity to a static team, you can define a team
retrieval service that dynamically returns a set of users and managers.

Before you begin


To perform this task, you must open the Process Designer desktop editor.

About this task


You can define a new team retrieval service either when you define a team, or when
you assign an activity to a team.

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

Setting up a routing policy (deprecated)


One of the options when routing the runtime tasks that are generated by activities, is
to establish a routing policy.

Before you begin


To perform this task, you must be in the IBM Process Designer desktop editor.
Before you can configure a routing policy, you must declare variables for your BPD.

About this task


When you define a policy, the users who receive the runtime task are determined by
the conditions that you specify.

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.

Parent topic:Assigning teams to BPD activities

68

Defining rules with a routing policy (deprecated)


When you establish a Routing Policy for a BPD activity, you establish rules to
determine the recipients of the activity as a runtime task.

Before you begin


To perform this task, you must be in the IBM Process Designer desktop editor.

About this task


Using rules, your task assignments can be dynamic, which ensures that activities
are routed to the appropriate individuals.
When defining rules, you can choose from the following rule types:
Table 1. Available rule types
Rule type
Swimlane
Participant Rule
User Attribute Rule
Expression Rule

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.

Open the Process Designer desktop editor.


Open a process application that contains a business process definition (BPD).
Click an activity in the BPD.
In the Properties page, click Assignments.
In the Assign To list, select Routing Policy (Deprecated). The Routing
Conditions (If) section becomes available.
6. Under Routing Conditions (If), click Add a column, and select the variable for
which you want to add the condition.
7. In the table, select Adv. The Advanced Assigned To (Then) section is
populated.
8. Under Advanced Assigned To (Then), click all in the following statement:
Advanced Lane Participants are users who match all of the following rules:
Choose all or any.
If you choose all, the runtime task is assigned to users who match all specified
rules. If you choose any, the runtime task is assigned to users who match at
least one of the specified rules.
If none of the conditions that you specify are met, IBM Business Process
Manager assigns the task to the swimlane for the rule to which this Advanced
Assignment applies.
69

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

Click enter value to display a


field in which you can enter
either anIBM 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.

- 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

Parent topic:Assigning teams to BPD activities

71

Assigning an activity to an ad hoc list of users


(deprecated)
An activity can be assigned to an ad hoc user list if the user group is defined
dynamically when a business process definition (BPD) instance is running.

Before you begin


To perform this task, you must be in the IBM Process Designer desktop editor.

About this task


The ad hoc group or list of users is maintained while the process instance exists on
the runtime Process Server.
Note: To assign activities to an ad hoc user list, create an activity with an underlying
service, upstream from the activity to be routed, to dynamically generate the user
list. The activity that generates the user list must include an output variable that
binds the user list to the follow-on activity to be routed.

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

Configuring conditional activities


You can use conditional activities to model steps which are either skipped or
completed during run time based on the values of specific process variables. The
decision to skip or complete a conditional activity can be made by the runtime user
or programmatically, based on scripted rules.
- Implementing a conditional activity
Complete the following steps to implement a conditional activity.
- Managing conditional activities by using the JavaScript API
You can find and select conditional activities for runtime execution by using the
following JavaScript API properties.
Parent topic:Creating a business process definition (BPD)

73

Implementing a conditional activity


Complete the following steps to implement a conditional activity.

Before you begin


To perform this task, you must be in the IBM Process Designer desktop editor.

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

Set selected conditional


activities

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

property to set selected


conditional activities.
Note:IBM Business Process Manager Performance Data Warehouse records
data that can be used to analyze the conditional activities. When a conditional
activity is skipped, a tracking point is created with SKIP appended to the name of
the skipped activity. A tracking point is created in the Performance Data
Warehouse TRACKINGPOINT views each time an activity is skipped. Using this
data, you can generate reports to show which activities are skipped and how
74

often those activities are skipped in a process instance.


Parent topic:Configuring conditional activities

75

Managing conditional activities by using the


JavaScript API
You can find and select conditional activities for runtime execution by using the
following JavaScript API properties.
The following table lists the available JavaScript API properties.
Table 1. JavaScript API properties
Property

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.

Parent topic:Configuring conditional activities

76

Creating an unstructured (ad hoc) activity


An ad hoc activity has no input wires and is started as required by knowledge
workers or according to predefined preconditions, rather than by a predefined
process flow. Such activities can be required or optional, and they can be defined as
repeatable or to run at most once. Knowledge workers can start unstructured
activities from the Activities section in the Process Instance details page in Process
Portal.

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

3. To specify the conditions as JavaScript expressions, click js to switch to the


JavaScript expression form, and enter the JavaScript expression for the
condition. To return to the default form, click js again.
4. To add more conditions, click the add icon.
- Example: Starting an unstructured (ad hoc) activity (JavaScript API)
This example shows you how to start an unstructured (ad hoc) activity.
Parent topic:Creating a business process definition (BPD)

78

Example: Starting an unstructured (ad hoc) activity


(JavaScript API)
This example shows you how to start an unstructured (ad hoc) activity.

Before you begin


To start an unstructured activity, the user must be a member of one of these groups:
- BPM admin
- Process/case admin
- Process/case instance owner
- Default lane team of the corresponding lane
An authorization check is performed by the REST API only when starting an
unstructured activity.

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);

var activitiyListProperties = new tw.object.ActivityListProperties();

var activityListFilter = new tw.object.ActivityListFilter();


activityListFilter.executionStateFilter = ["READY"];

activitiyListProperties.filters = new
tw.object.listOf.ActivityListFilter();
activitiyListProperties.filters.insertIntoList(0, activityListFilter);

log.info("querying for activity list ...");


tw.local.activities = pi.retrieveActivityList(activitiyListProperties)
log.info("activities found: " + tw.local.activities);

tw.local.aiid = // get the id of the activity you want to start (and


'actions' contains 'ACTION_START_ACTIVITY')

2. When you have the ID of the unstructured activity, use the


findActivityInstanceByID() call to retrieve the instance of the activity. Then
call start(...) to start the instance. Refer to the description of the

79

TWBPDSystemNamespace object in JavaScript API for IBM Process Designer. The


optional parameter taskOwnerUserId reassigns the task to the specified user id.

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();

Parent topic:Creating an unstructured (ad hoc) activity

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.

- Modeling non-reusable subprocesses


A subprocess is a logical collection of activities that exists only within its parent
process. Grouping related process elements in a subprocess simplifies the view of
the process. A subprocess hides the complexity of individual step details until the
subprocess activity is expanded.
- Working with linked processes
A process can call another process through a linked process activity. When the
linked process activity is triggered at run time, the linked process is run. After the
linked process is completed, the parent process resumes execution. When you
group together related activities in a separate BPD, instead of in a subprocess, you
can reuse that process in other processes that share that set of activities. For
example, the steps for creating a customer account might be common to several
different processes. If you group these steps together in a Create Customer
Account process, you can use linked process activities to call this process from all
processes that require it.
- Modeling event subprocesses
Event subprocesses are triggered by an event that occurs in the parent process.
Event subprocesses are similar to other subprocesses in that they are contained
within a parent process, and are not reusable outside of that process. They are
unlike other subprocesses in that they are not connected to other activities in the
process by incoming or outgoing connections, but are instead triggered by an
event or timer.

83

Parent topic:Creating a business process definition (BPD)

84

Modeling non-reusable subprocesses


A subprocess is a logical collection of activities that exists only within its parent
process. Grouping related process elements in a subprocess simplifies the view of
the process. A subprocess hides the complexity of individual step details until the
subprocess activity is expanded.

About this task


Subprocess activities are represented in the process diagram or case type activities

diagram by an activity element with an expandable subprocess marker:


Note:Case management functions are only available if you have IBM BPM
Advanced with the Basic Case Management feature installed.

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

navigation in the upper left of the canvas.


Parent topic:Subprocess types

86

Working with linked processes


A process can call another process through a linked process activity. When the
linked process activity is triggered at run time, the linked process is run. After the
linked process is completed, the parent process resumes execution. When you
group together related activities in a separate BPD, instead of in a subprocess, you
can reuse that process in other processes that share that set of activities. For
example, the steps for creating a customer account might be common to several
different processes. If you group these steps together in a Create Customer Account
process, you can use linked process activities to call this process from all processes
that require it.

About this task


Linked processes encapsulate logically related steps within a process while
retaining the high-level view of the parent process. However, linked processes differ
from subprocesses because they can be accessed and instantiated from processes
other than a single parent process. In previous product releases, linked processes
were known as nested processes.
Linked process activities are represented in the process diagram by an activity
element with a thick border and an expandable subprocess marker.

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

mapping to have the inputs or outputs of the linked process automatically


mapped to variable defined in the parent process.
- If the variables declared in the parent process do not match the variables of the
linked process inputs or outputs, you can manually select the variables to map.
- Calling a linked process dynamically
When you use a linked process as the implementation for an activity, you can use
an advanced option in the implementation properties to supply a predefined
variable to dynamically call one of many linked processes, depending on your
needs.
Parent topic:Subprocess types

88

Calling a linked process dynamically


When you use a linked process as the implementation for an activity, you can use
an advanced option in the implementation properties to supply a predefined variable
to dynamically call one of many linked processes, depending on your needs.

About this task


To use the dynamic option for a linked process, complete the following tasks first:
- Create a variable of type String in the parent process to hold the name of the
linked process that you want to run. Your parent process must also include the
logic to determine the value of this variable at run time. For example, the parent
process can include logic to set the value of this variable based on user input.
- Establish the input and output variables for each potential linked process so that
the parent process runs as expected regardless of which linked process is called.
To meet this requirement, the variables in all potential linked processes must be
the same. To map variables from the parent process to the linked process, follow
the steps described in Working with linked processes.
- Dependencies might exist between process applications and toolkits, as well as
between toolkits and other toolkits. For example, ProcessApp PA1 might depend
on Toolkit TK1, which in turn might depend on Toolkit TK2. This creates a
dependency chain: PA1 -> TK1 -> TK2. In order for the search to be started at the
beginning of the dependency chain (in PA1), the name of the invoked business
process definition (BPD) must be prefixed with a double slash (//). If a BPD in TK1
invokes a BPD dynamically without the double slash prefix, it will find only BPDs
down the dependency chain (that is, in TK1 and TK2, but not in PA1).
Restriction: The Diagram tab on the Process Performance dashboard can drill
down into subprocesses and statically linked processes that are defined in the
business process definition (BPD). It cannot drill down into dynamically linked
processes that are called by the process at run time.
To configure an activity to dynamically call one of many potential linked processes,
complete the following steps:

Procedure
1.
2.
3.
4.
5.

Open the parent BPD in the Process Designer.


Click the activity that you want to work with in the BPD diagram.
Click the Implementation tab in the properties.
Under Implementation, select the Linked Process menu option.
Click Select to choose one of the predefined linked BPDs from the library.You
must initially select one of the predefined linked BPDs for the dynamic
configuration to function properly.
6. Click the Data Mapping tab in the properties.Because you already created the
input and output variables for the linked process, the Data Mapping tab for the
activity in the parent process includes those variables.
7. 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.

89

8. Click the Implementation tab in the properties.


9. Click the indicator next to the Processing Behavior section heading to expand
the section.
10. Click the variable icon next to the Dynamic Sub-Process field to choose the
previously defined variable that provides the name of the selected process.Note:
At run time, the value of this variable cannot be null and it must exactly match
the name of an existing BPD.
11. Save the configuration.
Parent topic:Working with linked processes

90

Modeling event subprocesses


Event subprocesses are triggered by an event that occurs in the parent process.
Event subprocesses are similar to other subprocesses in that they are contained
within a parent process, and are not reusable outside of that process. They are
unlike other subprocesses in that they are not connected to other activities in the
process by incoming or outgoing connections, but are instead triggered by an event
or timer.

About this task


The event subprocess is a specialized subprocess that you can use to model eventhandling logic for a process or subprocess. It is triggered upon occurrence of a
configured start event, and as a result it is not connected to other steps through
sequence flow. It has access to the business objects (variables) of its parent
process and so can encapsulate steps that use those variables. When triggered, an
event subprocess can either interrupt the execution of its parent or it can run in
parallel.
You can use event subprocesses to handle exceptional process flows within your
process. For example, an event subprocess can be used to handle an out-of-stock
situation that arises during an order-fulfilment process. The out-of-stock event in the
parent process triggers the start event in the event subprocess, which contains
activities to order more stock or to check supplies at other locations.
An event subprocess can have only one start event. The start event implementation
is represented visually in the event subprocess activity in the parent process. It can
have any of the following implementation types:Table 1. Event subprocess
implementation types and visualizations
Start event implementation type Event subprocess visualization
Error

Message

Timer

- Message event subprocesses are triggered by a message event that often


originates from outside the business process definition (BPD) in which the event
subprocess is contained. A message start event might be used in a situation
similar to the situation described previously, where a message, such as an out-ofstock message, is received by the event subprocess and triggers a sequence of
activities.
- A timer start event might be used to model the steps to take when an activity within
the parent process is not completed after a specified amount of time. For example
91

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

Creating a user attribute definition


You can associate unique capabilities or qualities with one or more users by
creating user attribute definitions.

Before you begin


To perform this task, you must be in the IBM Process Designer desktop editor.

About this task


This procedure triggers dynamic group creation, which can be time consuming. You
can configure IBM Business Process Manager to deactivate these triggers. See
Deactivating dynamic group updates.
You can use defined attributes when you create teams that are based on a user
attribute rule. For more information, see Deprecated: Defining Team rules.
When a user creates a new user attribute definition in a process application, the new
attribute may need to be added to one or both of the following whitelists that
describe authorization on a per-user-attribute level depending on the authorization
requirement using a REST API for the specific attribute. These whitelists are
included in the 00static.xml file and can be overwritten by users in the
100custom.xml file.
- server/user-attributes/rest-authorization/public-attribute
- server/user-attributes/rest-authorization/self-managable-attribute
When accessed using a REST API, users that are not assigned privileges in the
ACTION_MANAGE_ANY_USERATTRIBUTE action policy:
- Can only see attributes of themselves and other users listed as public-attribute
- Can only see and update own attributes listed as self-managable-attribute
The following example shows how to add a new attribute to the list of selfmanagable attributes in the 100Custom.xml file.<server>
<user-attributes merge="mergeChildren">
<rest-authorization merge="mergeChildren">
<self-managable-attribute merge="append">CustomAttribute</self-managable-attribute>
</rest-authorization>
</user-attributes>
</server>

To create a user attribute definition:

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

Obtain current value


from...

Source

Obtain possible values


from...

Source

If you select Any


Allowed...
If you select List...

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

System tasks must be completed by an


automated system or service and are
automatically run without a need for user
initiation regardless of the type of lane in
which they are defined in a BPD
diagram. When you drag an Ajax service,
General System service, Integration
service, or Advanced Integration service
from the library to a BPD diagram,
Process Designer automatically creates
an activity with a System task type,
regardless of whether the service is
dragged to a system lane or to a
participant lane. Dragging an activity
from the palette to a system lane in a
BPD diagram automatically creates an
activity with a System task with the
Default System service selected. System
tasks that you place in a non-system lane
are also run by the system. In this way,
Process Designer automatically creates
the System implementation that you
need when you drag process
components onto a diagram. You can
also choose System Task and an
associated service for an activity
implementation, as described in
Implementing activities in a BPD.
A script uses JavaScript to access and
manipulate data.
Decision tasks are useful when you want
a decision or condition in a business rule
to determine which process
implementation is started. When you
drag a Decision service from the library
to a BPD diagram, Process Designer
automatically creates an activity with a
Decision task. You can also choose
Decision Task and an associated
Decision service for an activity
implementation, as described in
Implementing activities in a BPD.Note:
Decision tasks in IBM BPM are
equivalent to BPMN 2.0 Business Rule
Tasks.

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

Creating user interfaces for a BPD


Create customized user interfaces that a user sees for the process instance in
Process Portal.

About this task


IBM Business Process Manager provides a user interface for your instances in
Process Portal. You can either use the provided interface or you can create your
own user interface and make it the default user interface for all users. Optionally,
you can also create your own user interface that is customized for instance owners.
Attention: A process instance user interface must be implemented as a client-side
human service. You cannot implement it as a heritage human service.
These are the process instance user interfaces that you can create:
- The Default user interface that overrides the user interface that is provided by
IBM BPM. Any user that has permission to see the process instance in Process
Portal will see this interface. You can create a client-side human service and
specify it as the user interface. If you do not specify a client-side human service
here, the user interface that is provided by IBM BPM is used.
- The Instance Owners user interface is an optional user interface that you can
create for the team that is specified in the Instance owner team field in the
Overview page. You can create a client-side human service and specify it as the
user interface for the instance owners.

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

5. Map the process variables to the client-side human service variables. To


automatically map input properties with process variables, click the auto-map icon
.
6. Open the client-side human service, and click Run
to test the client-side
human service and the coach.Note: If you copied the template in step 4, remove
the defensive logic that shows an error when the instance ID is null.
7. To test the interaction between the user interface and the process:
A. Open the BPD and click Run Process in the toolbar.
B. Switch to the Inspector when prompted.
C. In the Inspector, select the process instance and click the Runs the Details UI
for the selected BPD Instance in the toolbar.
Process Portal opens in your default browser showing the process instance user
interface. You can view the user interface, enter data, and interact with the
process.
Parent topic:Creating a business process definition (BPD)

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

other actions that do not require any integrations or business rules.


Parent topic:Modeling processes

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

Client-side human service Use a client-side human


Building a client-side
service to implement an
human service
interactive task, a
dashboard, or a user
interface for a case or
process instance that
users can use to manage
cases or processes in an
application such as IBM
Process Portal. Client-side
human services run within
a web browser and can call
the server for data when
needed. Client-side human
services are authored in
the Process Designer web
editor, and can contain
coaches, client-side
scripts, services, and
events. Client-side human
services cannot use
heritage coaches.
Ajax service
Use an Ajax service when Building an Ajax service
you want to include a
control in a coach to
implement dynamic data
selection such as
automatically populating
drop-down lists and
automatically completing
edit boxes. An Ajax service
can pull data dynamically
from a connected data
source, such as a
database. You cannot call
an Ajax service from other
types of services, but an
Ajax service can call other
nested services.

105

Decision service

Integration service

Advanced integration
service

IBM Case Manager


integration service

Use a decision service


when you want a condition
to determine the
implementation invoked.
For example, when a
certain condition evaluates
to true, IBM BPM
implements the JavaScript
expression that you
provide. Decision services
cannot include Java or
Web Service integrations
directly. You can call a
decision service from any
other type of service and a
decision service can call
other nested services.
Use an integration service
when you want to integrate
with an external system.
An integration service is
the only type of service
that can contain a Java or
Web Service integration.
You can call an integration
service from any other type
of service and an
Integration service can call
other nested services.
Use an advanced
integration service when
you want to integrate with
a service created in IBM
Integration Designer.
Use an IBM Case Manager
integration service when
you want to integrate with
an IBM Case Manager
server

106

Building a Decision service

Building an Integration
service

Building an Advanced
Integration service

Integrating BPDs with IBM


Case Manager cases

General system service

Use a general system


Building a General System
service when you need to service
coordinate other nested
services or you need to
manipulate variable data.
For example, if you need to
implement data
transformations or
generate HTML for a
coach, you can use a
general system service.
General system services
cannot include Java or
Web Service integrations
directly. You can call a
general system service
from any other type of
service and a general
system service can call
other nested services.

Parent topic:Building services


Related information:
Examples of building services with heritage coaches

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

All service types


The following tools and components are available from the palette for all service
types:Table 1. Tools and components available from the palette for all service types
Component icon

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

Use to purposely throw an error and end


processing. You might, for example, use
an Error End Event component if you
return too many rows from a database
(over a limit that is normal and would bog
down the server).
Use to invoke an undercover agent
(UCA) from your service.
Use to listen for errors from the service
component to which it is attached.
Use to indicate a point in a service at
which you want IBM Business Process
Manager to capture the runtime data for
reporting purposes. For more information
about tracking data, see Enabling
processes for tracking and reporting.
Use to incorporate other services in your
current service. Nested services are
generally defined to perform specific,
repeatable functions such as exception
handling routines, integration with
outside systems, or data manipulation.
Nested services are often used in
multiple process applications and likely
reside in a toolkit. Note: Human and Ajax
services cannot be nested.
Note: You must use a nested service to
invoke an Advanced Integration service.
Use to send task-related alerts
(deprecated). In prior releases, the Send
Alert component was used to send alerts
to an IBM Process Portal user. Starting
in IBM Business Process Manager V8,
alerts can be retrieved only with the
TWSearch JavaScript API by querying
on tasks with the status of Alert.

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

Use to call methods from a Java class.


You can use the methods to complete
tasks like reading or writing files or
sending SMTP mail.
Use to integrate with an IBM Enterprise
Content Management system.

Heritage human service


The following tools and components are available from the palette for heritage
human services.Table 3. Tools and components available from the palette for
heritage human services
Component icon

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

Use the Business Action Language


(BAL) Rule component to author
business rules using natural language
technology

IBM Case Manager Integration service


The following tools and components are available from the palette for IBM Case
Manager services only:Table 5. Tools and components available from the palette for
IBM Case Manager services only
Component icon

Description
Use to integrate a case management
case in IBM Case Manager.

Parent topic:Building services


Related information:
Tools available from the palette for client-side human services

111

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.
IBM Process Designer supports business rule authoring tasks as performed by
business analysts and business users who are rule designers rather than
programmers. Business rule designers can express business logic using rule syntax
that resembles natural human language. This rule syntax is called Business Action
Language (BAL), which is a declarative language that relates business concepts to
business data and actions.
Business rules are an expression of business policy in a form that is understandable
to business users and that can be run by a rule engine. Business rules formalize a
business policy into a series of "if-then" statements. In Process Designer, business
rules are included in a business process definition (BPD) by adding a Decision
service to the process. Add a Decision service to a Process Application when the
actions that should take place in your process depend upon one or more conditions.
For example, if an employee holds the position of Director and submits a meal
expense for more than $250, then you can create a rule and set a variable in the
rule, such as approvalRequired, to route the process sequence flow into a specific
approval activity.
A Decision service contains one or more components. There are three types of
components:
- BAL Rule
- You can use the rule editor in this component to author business rules using
Business Action Language (BAL), a natural language technology.
- JRules Decision Service
- IBM Business Process Manager integrates with IBM WebSphere ILOG JRules
using the JRules Decision Service component. You can use this rule
component to connect to and implement rule applications that are available on
a JRules Rule Execution Server.
- Decision Table
- The Decision Table component contains a rule table. Each row in the rule table
represents a Boolean condition that evaluates to true or false at run time. When
a rule evaluates to true, the JavaScript expression that you provide as the rule
action is started.
When building a Decision service, follow these guidelines:
- Build your rule hierarchy so that rule conditions are ordered from most complex to
least complex.
- Create a final condition that is a catch-all rule. This rule is necessary if you cannot
guarantee that the variable that you want to modify in the rule will be set before
running the process that triggers the Decision service.
- Consider encapsulating your rules in a single-function Decision service, which
allows the service to be available to any other part of the process application that
needs the same rule logic.

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

work on in IBM WebSphere ILOG JRules Rule Studio.


- Adding a JRules Decision Service component to a service
When building a Decision service in Process Designer, you can include decision
services available on an ILOG JRules Rule Execution Server in your
implementation.
- Adding a Decision Table component to a service
You can add a Decision Table component to a service.
- 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.
- Decision service limitations
Some functions and variables are not supported in a Decision service.
Parent topic:Building services

114

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.

Before you begin


To perform this task, you must be in the IBM Process Designer desktop editor.

About this task


This scenario assumes that there is an existing business process definition called
Personalized Notification that includes a decision gateway named Send Alert. The
process includes a Decision service with BAL rules to decide whether a notification
is sent to the customer. The Decision service defines the conditions that must
evaluate to true in order for the notification step to be triggered. Using the following
steps, you can attach the NotificationRulesService to the Send Alert decision
gateway. The rules in the Decision service control whether the sequence flow
coming out of the gateway follows the "No notification" decision path, or the "Send
notification" decision path.

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

the rule (then) looks like this:then

set the message of notificationOut to

"Payment takes account overdrawn";

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.

You can find more information about decisions in the implementation of a


gateway, and attaching a Decision service to a gateway, in the related topic
"Attaching a Decision service to a decision gateway."
9. Test the Decision service and the BAL rules that you created and attached to the
decision gateway.
119

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.

E. The IBM BPM Debug Service opens in a new browser window.


F. When Process Designer prompts you to change to the Inspector interface,
click Yes. The prompt to switch to the Inspector perspective might be covered
up by the Debug window.
G. Click Step in the Debug window to run the Decision service one step at a time.
The Inspector clearly identifies any errors in the Execution State panel. The
Inspector also tells you where the error happened, and links directly to the
source of the problem. The Debug service browser window captures error and
exception messages. For more information about using the Debug service and
the Inspector window to identify and fix Decision service problems, refer to the
related topic "Debugging a Decision service."
H. If you make any changes to resolve errors in the Decision service or the BAL
rules, click Save, or use the Ctrl+S keyboard shortcut to save the Decision
service.

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

Creating rules using the rule editor


Attaching a Decision service to a decision gateway
Debugging a Decision service
Scenario: Exporting rules to a Rule Execution Server

121

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.

Before you begin


To perform this task, you must be in the IBM Process Designer desktop editor.
To create services, you must have access to a process application or toolkit in the
Process Center repository. Access to process applications and toolkits is controlled
by users who have administrative rights to the repository. For more information, see
Managing access to the Process Center repository.

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.

Parent topic:Building a Decision service


Related information:
Declaring and passing variables
Adding a BAL Rule component to a service
Adding a JRules Decision Service component to a service

122

Adding a Decision Table component to a service

123

Implementing an activity using a Decision service


You can implement an activity using a Decision service.

Before you begin


To perform this task, you must be in the IBM Process Designer desktop editor.

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

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.

Before you begin


To perform this task, you must be in the IBM Process Designer desktop editor.

About this task


When you attach a Decision service to a decision gateway, the process follows a
specific sequence line coming out of the gateway based on the result of the
conditions and actions in the rule components in the Decision service. If there are
multiple decisions in the Implementation properties for the gateway, the decisions
are evaluated from top to bottom and the path for the first decision that evaluates to
true is followed. If no decisions evaluate to true, the default path is followed.

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

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.

About this task


The following steps describe how to add a BAL Rule component to a sample
Decision service. The purpose of the sample service is to determine whether
approval is required for certain employee expenses. The sample service is a singlefunction Rule that can be called from any other service.
Restriction: The following variable types cannot be used with BAL rules in Decision
services:
- ConditionalActivity
- IndexedMap
- Map
- NameValuePair
- Record
- SLAViolationRecord
- SQLDatabaseType
- SQLParameter
- SQLResult
- SQLResultSetColumn
- SQLResultSetRow
- SQLStatement
- TWHolidaySchedule
- TWTimePeriod
- TWTimeSchedule
- TWWorkSchedule
- TaskListData
- TaskListItem
- TaskListProperties
- TaskListFilterProperties
- TaskListSortBySelectionType
- XMLDocument
- XMLElement
- XMLNodeList

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

Declaring variables for a BPD or a service in Process Designer

130

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.

About this task


You can use the BAL rule editor to build rules, add rule parts, statements, and
fragments, and replace placeholders with variables and values. Use the completion
menu in the editor to insert or edit constants, values, parts, or fragments of rule
statements. While you are creating or editing rules, the editor highlights errors to
help you identify and resolve problems in your rules.
A business rule consists of some or all of the following parts. The parts must be
defined in the following order:
1. definitions part (optional)
2. if part
3. then part
4. else part (optional)
For more information about the parts and structure of a business rule, refer to the
related topic "Business rule parts and structure."
The following steps describe how to author a rule using the rule editor. The rule is
implemented in a BAL Rule component as part of a sample Decision service. The
purpose of the sample service created in the procedure steps is to determine
whether approval is required for certain employee expenses. The sample service is
a single-function rule that can be called from any other service.

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

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.
For example, the business policy "refuse a loan to customers whose credit score is
below the minimum of 200" can be expressed as a business rule in the following
way:
- definitions

- set minimum_score to 200;


- if

- the credit score of the borrower is less than minimum_score


- then

- 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

- set minimum_score to 200;


This is a very basic illustration of the definitions part of a rule. For more information
about complex versions of the definition part, such as multiple occurrences of a
value, or adding a where clause to a definition to apply further restrictions on the
variables, refer to the related section in the WebSphere ILOG JRules InfoCenter,
"Understanding your rules -- Definitions." A related link is provided.

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

- the credit score of the borrower is less than minimum_score


This is a simple condition that is either true or false. The action is carried out if this
condition is true. The condition part of a rule can be made up of one or more
condition statements. For more information about conditions, refer to the section
"Understanding your rules -- Conditions" in the WebSphere ILOG JRules InfoCenter.

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

- set applicant to a customer;


where the category of this customer is Gold;
- if

- the value of the shopping cart is more than $100


- then

- apply a 15% discount


- else

- 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.

Parent topic:Adding a BAL Rule component to a service


Related information:
Understanding your rules: Definitions
Understanding your rules: Conditions
Understanding your rules: Actions
134

135

Defining variables in the rule editor


Variables are defined in the definitions part of a business rule.

Before you begin


Variables are accessible from business rules when you add them to the rule
vocabulary. For more information about verbalizing variables, refer to the related
topic "Adding and modifying Decision service variables."

About this task


You can use a variable to identify and then refer to an occurrence of something by a
convenient name. Use variables to make your business rules clear and easy to
understand. When you create a variable in a rule, the variable is only valid for that
rule, although the variable can be used in a all parts of the rule. Variable names
must be unique within a rule.

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

set customer to a customer;


set the cart to the shopping cart of customer;

- if

- the value of the cart is less than $100


- then

- apply 10% discount;

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."

Parent topic:Adding a BAL Rule component to a service


Related information:
Variable types

137

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.

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

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.

About this task


The BAL Rule component language is set to English by default, but you can change
the locale setting to change the language used in new BAL Rule components. Once
the locale is set, you can create new BAL Rule components using the updated
locale. However, if you add new rules to an existing BAL Rule component that was
created before you changed the locale, the added rules use the locale setting from
the BAL Rule component, not the updated locale preference setting.

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

Troubleshooting BAL rule editor errors


The Business Action Language (BAL) rule editor highlights errors with red underline
in the editing window.
To identify and correct an error in a rule, use the mouse to hover over the
highlighted error in the editor. When the error tip window is displayed, click the
underlined text in the error to go to the location of the error. Type in the editing
window to correct the error.

Error indicators in the rule editor


Errors in the rule editor are indicated by a wavy line under the section of the rule that
is invalid. Errors are underlined in red. Warnings are underlined in yellow.

Using Quick Fix to identify and fix errors


The Eclipse Quick Fix feature is available in the BAL rule editor. Quick Fix
messages offer suggestions to help you correct rule errors.
To see a proposed Quick Fix, click the light bulb icon next to the error indicator in
the rule editor window, or place your cursor on the error and press Ctrl+1.The
messages provide a list of possible corrections from which you can select the
appropriate fix.
To auto-correct an error from the quick fix message:
1. Put your cursor on the error indicator to display the error messages.

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.

3. From the list of suggestions, click to select the appropriate fix.

Parent topic:Adding a BAL Rule component to a service


140

141

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.

Before you begin


To perform this task, you must be in the IBM Process Designer desktop editor.

About this task


A Decision service might require input or output variables, or both. A service can
also include private variables for processing that occurs only within the service. For
more information about variables in a Decision service, refer to the related topic
"Declaring variables for a service."

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:

8. Select an existing Variable Type, or define a new variable type.


A. Click Select to set or modify the current variable type.
B. Click New to define a new variable type. For more information about defining a
new variable type using the Business Object editor, refer to the related topic
"Adding variable types and business objects to a Decision service."

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

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.

Default Decision service variables


The System Data toolkit is imported into the Process Center repository so that each
process application and toolkit that you create has access to IBM BPM system data.
The System Data toolkit includes assets that all IBM BPM projects require, including
variable types. The Decision service can use most of the pre-defined variables and
variable types, with a few exceptions.
For example, when you create a new variable in the Rule editor, and select a
business object (variable type) to associate with the variable, the following list of
default variable types is displayed:

The following variable types are not supported for Decision service variables:
- SQLResult
- XMLDocument
- XMLElement
- XMLNodeList

Decision service parameters


146

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."

Parent topic:Adding and modifying Decision service variables


Related information:
Adding variable types and business objects to a Decision service

147

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.

Before you begin


To perform this task, you must be in the IBM Process Designer desktop editor.
To create a custom business object (variable type), you must have write access to
a process application or toolkit in the Process Center repository. Access to process
applications and toolkits is controlled by users who have administrative rights to the
repository.

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."

Complex variables for hierarchical data


In IBM Business Process Manager, you can create a custom variable type by using
a base variable type or by defining a new complex structure. You can create rules
about complex data that is nested, or hierarchical. Data that is referenced within the
text of a rule is not limited to simple data types such as string, integer, or date. You
can create complicated rules with nested variable structure. For example, in the
Decision service shown in the following diagram, the variable paymentIn has the
variable type Payment, and contains other, nested variables.

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

Collections (lists) of variables


You can write rules against collections, or lists of variables, using Business Action
Language (BAL) rule constructs. You can use a variable to retrieve a collection (list)
of objects of a specific type. Use a list parameter in a business object when then are
numerous objects that your rule must run against, instead of just a single object. For
example, if you are writing a rule about an invoice, and there are multiple line items
in the invoice, then the invoice is actually a collection of line items. To write a rule
against the number of line items (if there are 10 or more line items, then process this
invoice manually), add a list parameter in a complex variable to your rule.
In the complex variable type, or business object, shown in the following diagram,
PastPayment is a list parameter, which means that it contains multiple objects of the
String, Decimal and Date variable type. To identify a variable as a collection or list,
click to select the Is List option under Parameter Properties.

Predefined variable types


Many pre-defined variable types are provided by the IBM BPM System Data toolkit.
These variables are defined as business objects. You can open a business object in
Process Designer and review the Documentation field to learn when and how to use
each variable type. For example, to open the Record business object included in
the System Data toolkit, complete these steps:
1. Open a process application in Process Designer.
2. Click the indicator next to the Toolkits category to see a list of toolkit
dependencies for the current process application.

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.

Parent topic:Adding and modifying Decision service variables


Related information:
Declaring variables for a BPD or a service in Process Designer
Types of variable definition

152

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.

Before you begin


To perform this task, you must be in the IBM Process Designer desktop editor.

About this task


To test a rule component and the rules it contains, you can load the Decision service
with default data and then step through the activities in your business process
definition to see the generated process data as it interacts with the business rules
you have defined. For example, if you set a breakpoint on an activity that has an
associated Decision service, you can make sure that the Decision service is
producing the data you expect, and make sure that there are no error messages or
exceptions being produced by the Decision service as it runs.

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

exceptions provide information that is helpful when you are troubleshooting


Decision service execution errors.
Parent topic:Building a Decision service

154

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.

Before you begin


To perform this task, you must be in the IBM Process Designer desktop editor.

About this task


There are several types of Decision service problems that you can troubleshoot
using the Debug Service and the Inspector. For example:
- Results from running the Decision service are not what you expected.
- Running the Decision service results in an exception and you need to identify the
process step that generates errors.
To enable the Debug Service to step through the Decision service execution, set a
breakpoint on each activity within the Decision service before running the debug
function.

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

7. When Process Designer prompts you to change to the Inspector perspective,


click Yes.Note: The prompt to switch to the Inspector perspective might be
covered up by the Debug window.
8. The Inspector opens the currently running service in the Services in Debug tab
and shows progress through the service, using a hierarchical tree in the
Execution State panel to show the process step that is running.

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.

Parent topic:Testing a Decision service


Related tasks:
Resolving errors

156

Exception messages in Decision service testing


You can review exception messages that result from Decision service testing. The
exceptions provide information that is helpful when you are troubleshooting Decision
service execution errors.
When troubleshooting Decision service errors, the following information applies to
the exception messages:
- When a rule component is running, exception messages include the Decision
service name and step name.
- Exceptions in a rule condition cannot be traced to a specific rule.
- Exceptions in a rule action can be traced to a specific rule.
- The rule name includes a number part that corresponds to the order of the rules in
the BAL rules component, such as 1, 2, 3, or 4. If there are numerous rules in a
BAL rules component, this number helps you track down the location of the error.

Example of a null exception


If a variable value cannot be resolved, this problem results in a null exception, as
shown in the following example:ilog.rules.res.session.IlrRuleServiceException:
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

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

Unsupported variable type


If you author a rule that uses an unsupported variable type, an exception message
similar to the following example is displayed:An error occurred in simpleTypeTestService service, at
rule 1 in step SimpleTypeRuleStep.
Detail message: Ruleset
/b_c54531e1028c40a185bf1115183a3420/1.0/_bd1ea7af45d14fa9afcea38113db2c35_8cf262cc674e4561bce84c00820bc88e/1.0 parsing
failed 'IRL/rule_1.irl', line 8:
error: incompatible values involved in assignments
com.lombardisoftware.core.TeamWorksException:
An error occurred in simpleTypeTestService service, at rule 1 in step SimpleTypeRuleStep.
Detail message: Ruleset
/b_c54531e1028c40a185bf1115183a3420/1.0/_bd1ea7af45d14fa9afcea38113db2c35_8cf262cc674e4561bce84c00820bc88e/1.0 parsing
failed 'IRL/rule_1.irl', line 8:
error: incompatible values involved in assignments
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)

Uninitialized variable produces a NullPointerException


Using an uninitialized variable in a BPEL process can result in various exception
errors. In IBM BPM, all private or complex variables and all lists (arrays) must be
initialized before you use them in a business process definition or Decision service.
If you do not initialize a private or complex variable or list, you may receive runtime
errors, such as the following example, or notice that the Coach controls to which the
variables are bound do not behave as expected. For more information about errors
produced by uninitialized variables, refer to the related topic "Uninitialized variable
or NullPointerException in a Java snippet."An error occurred in NotificationRules service, at rule 1
in step AlertRuleStep.

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)

Parent topic:Testing a Decision service


Related information:
Uninitialized variable or NullPointerException in a Java snippet

159

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.

About this task


This scenario assumes that you previously completed the steps outlined in
Scenario: Creating a Decision service in a Personalized Notification process. Upon
completion of that scenario, your business process definition includes a Decision
service called NotificationRulesService, which contains a BAL Rule component
called AlertRules. For the purposes of the current exporting scenario, assume that
the rules you wrote for the AlertRules component also apply to other processes in
your organization, so you want to share the rules with your co-workers, who are
developing business rules using IBM WebSphere ILOG JRules. You can export the
rules you created in Process Designer, import them into Rule Studio, deploy the
rules to a Rule Execution Server (RES) , and then connect your Decision service to
the RES using a JRules Decision Service component.

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

3. Deploy the rules to the rule execution server (RES).


A. In Rule Studio, select the RuleApp which contains the AlertRules and click
Deploy a RuleApp to one or more Rule Execution Servers.
B. Select an existing Rule Execution Servicer and deploy the RuleApp to the
server.
For more information, see the related topic about deploying from Rule Studio in
the IBM WebSphere ILOG JRules BRMS Information Center.
4. Add a JRules Decision Service component the Decision service and connect it to
the RES.
A. Configure your Decision service to include a JRules Decision Service
component. When you specify the correct rule execution server and port
settings, the JRules Decision component establishes a connection between
Process Designer and the Rule Execution Server that contains the imported
rule project.
B. Make sure that you are editing the NotificationRulesService Decision service.
C. Remove the AlertRules BAL Rule component that contains the rules you
exported.
D. Replace the BAL Rule component with a JRules Decision Service component.
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.
E. Select the new JRules Decision Service component, then click
Implementation in the Properties tab.
F. In the Discovery section, enter the following information to connect to the Rule
Execution Server that contains the rules that you want to use.
- Server: Select the Rule Execution Server (RES).
- SOAP Port: Specify a port for the SOAP connection if the Rule Execution
Server is running on WebSphere Application Server.
- User name: Enter a user name if the JRules server requires a secure
connection.
- Password: Enter the password if the JRules server requires a secure
connection.
G. Click Connect.
H. In the Rule section, select the Rule App that you want from the menu, then
select the version that you want to use.
I. Click Generate Types.
You can find more information about adding a JRules Decision Service
component in the related topic about configuring a remote Decision service.
5. Map the variables to make sure that the variables used in the rules on the Rule
Execution Server correspond to variables defined in Process Designer.
A. Click the Properties tab in the JRules Decision Service panel.
B. In the Properties section, click Data Mapping.
C. Click the auto-map icon in upper right corner of the Input Mapping section.
D. In the Create variables for auto-mapping window, click to select each
variable that you want to create in your Decision service and then click OK.
E. Click the auto-map icon in upper right corner of the Output Mapping section.
F. In the Create variables for auto-mapping window, click to select each
variable that you want to create in your Decision service and then click OK.
161

6. Save the updated Decision service.

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

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
work on in IBM WebSphere ILOG JRules Rule Studio.

Before you begin


To perform this task, you must be in the IBM Process Designer desktop editor.

About this task


Process Designer provides the capability for non-developers to express business
logic using Business Action Language (BAL) in business rules. In most cases,
business rules can be fully developed and implemented using Process Designer.
However, in a situation where the business logic reaches levels of complexity not
supported within IBM Business Process Manager, the business logic can be
exported without modifications to IBM WebSphere ILOG JRules Rule Studio. The
export procedure produces a complete business rules project suitable for continued
work within JRules. After exporting the rules, importing into Rule Studio, and
deploying the rules on a Rule Execution Server, the business process in Process
Designer can consume the resulting rule application using a remote decision service
provided by JRules.

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

the WebSphere ILOG JRules InfoCenter.


- Configuring a remote Decision service
You can include a rule application from a remote ILOG JRules Rule Execution
Server in your Decision service.
Parent topic:Building a Decision service
Related information:
Importing a rule project in Rule Studio

164

Configuring a remote Decision service


You can include a rule application from a remote ILOG JRules Rule Execution
Server in your Decision service.

Before you begin


- Export the rules to an Eclipse rule project file.
- Using IBM WebSphere ILOG Rule Studio, import the project .zip file to create a
new Rule Studio project.
1. Click File > Import > General > Existing Projects into Workspace.
2. Click Select archive file. Click Browse to navigate to the location where you
saved the exported rule project file and select the file.
3. Select an existing project where the rules will be imported, or create a new Rule
Studio project, then click Finish.
4. Deploy the imported rules to the Rule Execution Server. For more information,
see the related topic "Deploying from Rule Studio." A related link is provided.

About this task


After you have exported rules in a rule component from IBM Business Process
Manager, and imported the rule project into IBM WebSphere ILOG Rule Studio, you
can configure your Decision service to include a JRules Decision Service
component. When you specify the correct rule execution server and port settings,
the JRules Decision component establishes a connection between Process
Designer and the Rule Execution Server that contains the imported rule project.

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

Enter a user name if the JRules server


requires a secure connection.
Enter the password if the JRules server
requires a secure connection.

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

Adding a JRules Decision Service component to a


service
When building a Decision service in Process Designer, you can include decision
services available on an ILOG JRules Rule Execution Server in your
implementation.

Before you begin


To perform this task, you must be in the IBM Process Designer desktop editor.

About this task


IBM Business Process Manager integrates with IBM WebSphere ILOG JRules by
providing a JRules Decision Service component. This rule component enables you
to use rule applications available on a JRules Rule Execution Server for your IBM
BPM implementations.
Why should you choose using a JRules Decision Service component over creating a
standard web service when connecting to an IBM Operational Decision
Management (ODM) server, which is IBMs recently renamed ILOG JRules Rule
Execution Server? The JRules Decision Service component is specifically designed
for calling a JRules decision service. It has a closer conceptual mapping to the
JRules decision service called and, therefore, is a more efficient representation of it
in your business process model. A JRules Decision Service component can handle
decision services hosted on either a WebSphere ILOG JRules BRMS 7.1,
WebSphere Operational Decision Management 7.5, or IBM Operational Decision
Management server.
Conversely, the web service will treat the service called as it would any other
generic service; that is, the web service has no corresponding model representing
the JRules decision service called. Each time a JRules server version changes, you
will need to modify the web service.
The following procedure describes how to use the JRules Decision component to
connect to a WODM server and invoke the rule applications and rule sets available
on that server as decision services.
Before using the JRules Decision Service component in your Rules service, review
the following requirements:
- For a secure connection to a Rule Execution Server running on WebSphere
Application Server, you must provide the SOAP port and, if necessary, the user
name and password for the Rule Execution Server. This secure connection
enables you to choose the applications and rule sets that you want to use from the
Rule Execution Server.
- If you connect to a Rule Execution Server that is running on WebSphere
Application Server, but the Rule Execution Server is not properly configured for
security or you are not able to provide the SOAP port, user name, and password,
then 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

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.

Parent topic:Building a Decision service


Related information:
Adding a server configuration
Adding a Decision service to a process
Declaring and passing variables

169

Adding a Decision Table component to a service


You can add a Decision Table component to a service.

Before you begin


To perform this task, you must be in the IBM Process Designer desktop editor.

About this task


The Decision Table component contains a table with a rule condition in each row.
Each row in the table represents a Boolean condition that will evaluate to true or
false at run time. The condition evaluates to true only if the values of all the
associated variables produce matches with the provided values. The following
information applies to the Decision Table component.
- The double-dash (-) value in a variable field indicates that any variable value is
considered a match.
- When a rule evaluates to true, the JavaScript expression that you provide as the
action is started. This expression may contain any valid JavaScript.
- A rule only executes the JavaScript expression once per a rule, using the
JavaScript expression associated with the first condition that evaluates to true.
The steps in this procedure demonstrate how to add a Decision Table component to
a decision service using example values. For your own implementation, you might
not use the same steps or names.

Procedure
1.
2.
3.
4.

Open the Process Designer desktop editor.


Open a process application that contains a business process definition (BPD).
Create a Decision service.
Drag the Decision Table component from the component palette to the service
diagram.
5. Click the Properties tab, then enter ExpenseApproval as the Decision Table
component name.
6. Click the Variables tab.
7. Click Add Input to add variables to the service.
8. Replace Untitled1 in the Name field with request.
9. Click Select next to Variable Type and select the type from the list.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 and select Activity Wizard
from the list of options.
10. Click Add Private.
11. Replace Untitled1 in the Name field with approvalRequired .
12. Click Select next to Variable Type and select the Boolean type from the list.
13. Click the Decisions tab to open the rules editor.

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

Authoring rules using JavaScript in a Decision


Table component
You can create rules using JavaScript in a Decision Table component.

Before you begin


To perform this task, you must be in the IBM Process Designer desktop editor.

About this task


The following steps describe how to create a sample business rule using the
Decision Table editor and JavaScript. The rule in the sample is used to determine
whether approval is required for certain employee expenses. The sample is a singlefunction rule that can be called from any other service. For your own
implementation, you might not use the same steps or names.

Procedure
1.
2.
3.
4.

Open the Process Designer desktop editor.


Open a process application that contains a business process definition (BPD).
Create a Decision service.
Drag a Decision Table component from the palette to the Decision service
diagram, and edit the component parameters as described in the related topic
"Adding a Decision Table component to a service."
5. Click the Decisions tab to open the rules editor.
6. In the rules editor, click the plus sign to add a variable (column) to the first rule
(row).
7. From the variables displayed, pick the amount variable from the request
structure.
8. Type >250 as the value.
9. 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.
10. From the variables displayed, pick the type variable from the request structure.
11. Type "director" as the value.
12. In the Action Requirement field for the first rule (row), type Requires
Approval.
13. In the rules editor, click the Action section to expand it.
14. For the Requires Approval requirement, enter the following JavaScript code for
the Action: tw.local.approvalRequired = true; The rules editor includes the
rule shown in the following image:

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."

Parent topic:Adding a Decision Table component to a service


Related information:
Adding a Decision service to a process
Adding a Decision Table component to a service

173

Decision Table controls


You can use the toolbar options in the conditions editor window to add, remove, or
move conditions in the table.
Table 1. Toolbar options in the conditions editor window
Option

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.

Parent topic:Adding a Decision Table component to a service

174

Specifying variable values using JavaScript


You can use JavaScript in rules to set variable values.
The following samples demonstrate how to specify the value of a variable when
using the rules editor:
Table 1. Samples for setting variable values
Sample
"ok"
1.4
{"A", "B"}
!={"A", "B"}
1..5
>3
<3
>=3
<=3
{1,3,5}
{1,3,5..10}
!={1,3,5..10}
true
false

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

Parent topic:Adding a Decision Table component to a service

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

Decision service limitations


Some functions and variables are not supported in a Decision service.
When you are creating or modifying rules using the rule editor, the following
limitations apply:
- You cannot create complex rules that use decision tables and Business Action
Language (BAL) rules in a single rule component.
- You cannot write rules that include behaviors (methods).
- The rule editor does not support rules that include data with complex (many-tomany) relationships.
- The rule editor does not support the following business objects (variable types):
- SQLResult
- XMLDocument
- XMLElement
- XMLNodeList
The following types of rule components are not supported, or are supported with
some limitations:
- Decisions that require complex algorithms such as chaining, Rete, or stateful
execution are not supported; only sequential execution is supported.
- Decisions that reference runtime process instance data cannot be exported for use
in IBM WebSphere ILOG JRules Rule Studio.
- Multi-channel decisions are not supported.
- Decisions that use methods, custom verbalization and model abstraction are not
supported.

Parent topic:Building a Decision service

177

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, client-side
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.

Before you begin


To perform this task, you must be in the IBM Process Designer desktop editor.
To create services, you must have access to a process application or toolkit in the
Process Center repository. Access to process applications and toolkits is controlled
by users who have administrative rights to the repository. For more information, see
Managing access to the Process Center repository.

About this task


Building a client-side human service is an iterative process in which many of the
steps can be done in any order. In general, you create a flow, create the user
interface through one or more coaches, and then test and fix problems. The steps in
the procedure are in a suggested order but typically you will go back and forth
through the steps as you iteratively build the client-side human service
implementation. For example, you could create a simple client-side human service
that has a couple of coaches and variables and test it in one iteration. You then
expand the client-side human service by adding more coaches and variables, clientside scripts, decisions, and other details in later iterations. Similarly, you could
create some variables immediately and create other variables as you need them.
Remember:IBM BPM also has heritage human services. While client-side human
services flow entirely in the web browser, heritage human services instead flow on
the server. For more information, see Difference between client-side human
services and heritage human services.

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

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.

Before you begin


To perform this task, you must be in the IBM Process Designer desktop editor.
To create services, you must have access to a process application or toolkit in the
Process Center repository. Access to process applications and toolkits is controlled
by users who have administrative rights to the repository. For more information, see
Managing access to the Process Center repository.

About this task


A heritage human service consists of a server-based flow that can include scripts,
events, decisions, and coaches. When the flow reaches a coach, users see the
web-based form that is defined in the coach layout. The form displays processrelated data to users and collects input from those users.
The steps in this procedure start from the business process definition diagram, add
an activity, and then define the heritage human service that is associated with that
activity. If you are not creating the heritage human service for a BPD or you want to
create the heritage human service first, create the heritage human service using the
library and then start the procedure at step 7..

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

includes a simple diagram.


The coach in the diagram has the following default content:
- If you added one or more business process variables that are primitive types,
the coach has an appropriate stock control in the layout for each of these
variables.
- If you added one or more business process variables that are complex types
and they have an associated coach view, the coach has that coach view for
each of these variables.
- If you added one or more business process variables that are complex types
and they do not have an associated coach view, the coach has a placeholder
message for each of these variables. When you are building the coach, you
replace each placeholder with a coach view that is appropriate for the variable
and how the coach is using it. For example, if you have a Customer business
object, you could replace the placeholder with a Customer View coach view
that displays customer data in a set of text fields.
- A button that provides the boundary event that you can use to wire the coach
to the end node.
This default content is for your convenience and you can use it or replace it.
9. In the heritage human service diagram, create the service flow by adding
elements from the palette and wire the elements together to create a flow. See
Service components in Process Designer for information about the elements that
you can add to the diagram. Restriction: You cannot wire out from a coach
unless the coach (or one of its child coach views) contains at least one element
that fires a boundary event. You can use the Button stock control to fire a
boundary event, or you can create a custom control that fires a boundary event.
For more information, see Coaches toolkit: Button stock control.
10. In the Variables page, add business process variables to support your service
flow.Tip: If you provide HTML code as a default value for a variable, wrap the
code using the other type of quotation mark. For example, if the HTML values
use double quotation marks, wrap the entire code in single quotation marks as
shown in the following example:'<font color="#f08080"><b>Some text!</b></font>'
11. In the Coaches page, create the user interfaces used in the service flow. For
more information, see Building coaches.
12. Click Save in the main toolbar.
13. To view the service flow in a web browser, click the button.
14. Iterate through steps 7 - 11 until the service flows correctly and the user
interface is correct.
15. If you want to expose the heritage human service outside of the business
process (for example, in the Process Admin Console or as a page in Process
Portal), set the exposure in the Overview page of the service. For more
information, see Exposing heritage human services.If you are building the
heritage human service in a toolkit instead of in a process application, to expose
the heritage human service as a page in Process Portal, you must also do the
181

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.

Parent topic:Building services

182

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.

Before you begin


To perform this task, you must be in the IBM Process Designer desktop editor.
To create services, you must have access to a process application or toolkit in the
Process Center repository. Access to process applications and toolkits is controlled
by users who have administrative rights to the repository. For more information, see
Managing access to the Process Center repository.

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

Building an integration service


Build an integration service when you want a flow to interact with an external
system.

Before you begin


To perform this task, you must be in the IBM Process Designer desktop editor.
To create services, you must have access to a process application or toolkit in the
Process Center repository. Access to process applications and toolkits is controlled
by users who have administrative rights to the repository. For more information, see
Managing access to the Process Center repository.

About this task


For example, you may want users to choose from a list of products available from a
common site on the internet. In that case, you can build an Integration service that
calls a web service to display the list of options. Integration services are the only
services that can include Web Service Integration and Java Integration components
as well as content integration. For more information about inbound and outbound
integrations, see Integrating with web services, Java and databases.

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

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).

Before you begin


An advanced integration service is a collaboration between a business user working
with IBM Process Designer and an integration developer working with IBM
Integration Designer.
For example, your business process may need a list of computer parts in your
warehouses in Canada. Checking with an integration developer, you realize that a
service is being built in Integration Designer to query the Canadian warehouses and
return an inventory list of the computer parts available. You could create an
advanced integration service that would use this Integration Designer service as an
activity in your business process. Note: Advanced integration services are available
only with IBM Business Process Manager Advanced.
As suggested in Best practices when using IBM Integration Designer and IBM
Process Designer together, collaborate before defining your advanced integration
service. For example, since you may want to share this and other advanced
integration services with many business processes, you might select a toolkit to
contain all your advanced integration services.
To perform this task, you must be in the IBM Process Designer desktop editor.
To create services, you must have access to a process application or toolkit in the
Process Center repository. Access to process applications and toolkits is controlled
by users who have administrative rights to the repository. For more information, see
Managing access to the Process Center repository.

About this task


To build an advanced integration service, follow these steps.

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

designed in Integration Designer. If you want to catch a specific error using an


error event in your process model, enter an error name that matches the error
code in the catching error event.
Add a description for the parameter in the Documentation field. Selecting Is List
means the parameter is an array (contains a set of data). In the Parameter Type
field, set the data type for the parameter.
6. The Advanced Integration Service section contains fields used in Integration
Designer that will be initially empty with the exception of Can be used with
service? The fields will be filled in when the service is implemented in Integration
Designer. Can be used with service? can also be changed at that time depending
on the implementation in Integration Designer.
- Module name: The name of the module in Integration Designer containing the
service implementation.
- Export name: The name of the export of the module that exposes the service
implementation. An export is the endpoint to be used when invoking the service.
- Operation name: The name of the operation of the service to be invoked.
- Can be used with service?: Not all implementations of advanced integration
services can be used with a service. If the implementation cannot be used with a
service, this field will be set to No.An advanced integration service can always
be used by a Business Process Definition whether the Can be used as service
field is set to Yes or No. It can also be used by the following services if the field
is set to Yes: a general system service, a human service or an integration
service. Do not use an advanced integration service with these services if you
see a No in this field or these services will experience unexpected behavior.
The Yes or No value itself is determined by the preferred interaction style and
operation type used by the associated export in Integration Designer.
- Asynchronous style with a one-way operation type: Yes.
- Asynchronous style with a request-response operation type: No.
- Synchronous style with a one-way operation type: Yes.
- Synchronous style with a request-response operation type: Yes.

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

As discussed earlier, your service is a collaborative arrangement. Should you move


your advanced integration service to another toolkit, notify the integration developer
who implemented your service. Your service and its implementation by Integration
Designer are decoupled, which means that even though you may move a service in
Process Designer there will not be an automatic corresponding movement in the
implementation by Integration Designer.
The integration developer should use the refresh function to identify the
implementation that he needs to move and recouple with the advanced integration
service you moved in Process Designer.

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

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
other actions that do not require any integrations or business rules.
Prerequisite: To build a General System service, you must be in the IBM Process
Designer desktop editor.
General system services are likely to be called directly from a BPD or from a Human
Service. General System services can include only basic service components, such
as scripts, and cannot contain Coaches or integration steps (Web Service
integration, Java integration, or Content integration). General System services can
be nested within any other type of service.
To create services, you must have access to a process application or toolkit in the
Process Center repository. Access to process applications and toolkits is controlled
by users who have administrative rights to the repository. For more information, see
Managing access to the Process Center repository.
To create a General System service, perform the following steps.
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 click General System
Service.
4. 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.
Parent topic:Building services
Related information:
Examples of building services with heritage coaches
Service types

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

.Note: For information about implementation options for Start events in a


subprocess or event subprocess, see Subprocess types.
- Intermediate event

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

Parent topic:Modeling events

194

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.

Before you begin


To perform this task, you must be in the IBM Process Designer desktop editor.

About this task


In a business process definition (BPD), use timer events to control when activities
occur within a process flow or when a process flow takes a specific path. That is,
use timer events to do the following things:
- Create a delay to prevent an event or activity from immediately triggering.
- Create an escalation to handle when an activity fails to complete in a timely
fashion.
- Create a timeout to prevent a flow from waiting indefinitely.
Each timer event has an associated timer. The time interval for the timer is
calculated according to the configuration that you specify in the implementation
properties for the timer event. Normally, when the specified time interval elapses,
the timer event triggers and the sequence flow goes out from the timer event to a
subsequent node. However, when a BPD instance suspends, the timer events do
not trigger. All of the timers within the timer events continue to track the passage of
time though. If any timers elapse while the instance is suspended, their associated
timer events wait for the BPD instance to resume before they trigger.
For modeling delays, use timer intermediate events that have sequence flow lines
that are entering it and sequence flow lines that are leaving it.

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

events are attached to an activity in a BPD.


When a running process instance reaches an activity that has a timer boundary
event, a timer starts. When the timer elapses, the process follows the sequence flow
195

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

intermediate event to specify the timeout period.


For information about creating an event gateway, see Modeling event gateways.

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

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.
Prerequisite: To model message events, you must be in the Process Designer
desktop editor.
Incoming messages can originate from a message event in a process, from starting
an undercover agent (UCA) in a service, from a Service Component Architecture
(SCA) service, from a web service that you create, or from a message that you post
to the JMS Listener. If you want to create web services to initiate inbound requests
from external systems, see Publishing IBM Business Process Manager web
services.
If you want to post a message to the JMS Listener, the Event Manager has a
defined XML message structure that it must receive from an external system. For
more information about the required message structure, see Posting a message to
IBM Business Process Manager Event Manager.
Outgoing messages can be received by a message event in a process, can be sent
to call an external service, or can be received by the start event in another process
or processes. To learn how to configure message events to send messages, see
Using intermediate message events and message end events to send messages.
You can include the following types of message events in your BPDs:
Table 1. Available types of message events
Event type
Start event

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

Message that is configured Use to receive a message


to receive
event. Intermediate events
can be attached to
activities within your BPDs
or they can be included in
the process flow, which is
connected with sequence
flows. An intermediate
event that is attached to an
activity, rather than the
swimlane, is known as a
boundary event. Boundary
events can optionally either
interrupt and complete the
activity, or be triggered
repeatedly.
Message that is configured Use to send a message
to send
event. Intermediate events
can be included in the
process flow, which is
connected with sequence
flows.
Message that is configured Use to send a message
to send (End events can
event at the end of a path.
only send messages)

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

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. Incoming messages can originate from a message event in a
process, from starting an undercover agent (UCA) in a service, from a Service
Component Architecture (SCA) service, from a web service that you create, or from
a message that you post to the JMS Listener.

Before you begin


To perform this task, you must be in the IBM Process Designer desktop editor.

About this task


The general information that applies to all types of message events are covered
in Modeling message events .When modeling start message events that use a UCA
for the triggering mechanism, be aware of the following:
- When a message is received by a start message event (specifying that an
incoming message is to start a process at run time), a new instance of the process
is created and a unique BPD instance ID is assigned to it.
- If you use multiple start message events in a single BPD, use a separate
undercover agent for each. If you use the same undercover agent for multiple start
message events, IBM BPM instantiates multiple instances of the BPD.
For example, you might want an employee on-boarding process to start when a
record for each new employee is created in your HR system. When the record is
created, the system sends an event to IBM Business Process Manager. IBM BPM
captures the event and starts the follow-on steps for each new employee such as
setting up the necessary space and computer equipment, requesting and creating a
security badge.

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

B. If Interrupt Parent Process is not selected, the Repeatable option is


available. If the start message event can be triggered more than once, select
the Repeatable option so that the subprocess can receive multiple messages.
6. To use UCA for triggering a start 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. The Durable Subscription check box is not available for start message
events, only for intermediate message events as described in the following
section.
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: UCAs 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 a start message event, complete the
following actions in the Message Trigger section.
A. For Triggering Mechanism, select SCA Service.
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 start 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.
202

- 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

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.
Intermediate message events can be attached to activities within your BPDs or they
can be included in the process flow, which is connected with sequence flows. Drag
an intermediate message event onto the swimlane to create an intermediate
message event. If you drag an intermediate message event onto an activity, it
becomes a boundary message event. You can change either existing message
event type to the other type by dragging it to or from the swimlane or activity.Tip:
When you add message events in a BPD, be aware of the general information in
Modeling message events that applies to all types of message events.

Before you begin


To perform this task, you must be in the IBM Process Designer desktop editor.

About this task


For a receiving intermediate message event, you can use an undercover agent
(UCA) for the message triggering mechanism.
You can also use a Service Component Architecture (SCA) service as the
triggering mechanism.
Tip: To build a sample inbound integration that includes an intermediate message
event included in the process flow, which is connected with sequence lines, see
Building a sample inbound integration.

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

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 a local variable
in the BPD.
Parent topic:Modeling message events
Related information:
BPMProcessInstancesCleanup command
BPMDeleteDurableMessages command
Creating and configuring an undercover agent for a message event
Attaching the undercover agent to the message event
Using Service Component Architecture to interact with processes

208

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.
For example, you might want to call an external service or to send a message to be
received by the start event in another process or processes. Message events can be
included in the process flow, which is connected with sequence lines. Intermediate
message events have both incoming and outgoing sequence flows, while message
end events have only incoming sequence flows. Tip: When you add message
events in a BPD, you should be aware of the general information in Modeling
message events that applies to all types of message events.

Before you begin


To perform this task, you must be in the IBM Process Designer desktop editor.

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

information from the event.


9. If you created an end event, specify the input mapping.
A. On the Properties tab, click Data Mapping.
B. Open the Input section.
C. Map each input variable to a local variable in the BPD. For each variable,
select it then complete one of the following actions.
- Click the variable selector icon to map each input variable to a local variable
in the BPD.
- Enter a literal value or the name of a local variable.
- To use the default value from the variable, click Use default. When you
enable this check box, the variable selector icon is disabled.
Parent topic:Modeling message events
Related information:
BPMProcessInstancesCleanup command
BPMDeleteDurableMessages command
Creating and configuring an undercover agent for a message event
Attaching the undercover agent to the message event

210

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.
You can include an intermediate message event in your BPD when you want to
model a message event that is sent or received while a process is running, or you
can use a start event to receive a message event or use an end event to send a
message event.
The default behavior for intermediate incoming message events is that they are
received by all snapshots in all process applications that refer to the undercover
agent and that have event message properties that match the correlation values.
For start message events, the default behavior is that they are used on the tip in
Process Center and in the default snapshot on IBM Process Server.
To change that default behavior, select the check box labeled Target the snapshot
of the installed process application that contains this BPD or Target the
snapshot of the installed process application that contains this service. (The
label depends on your context.) You encounter the check box when you are
configuring the undercover agent for a message event. If you select the check box,
at run time start message events are targeted in the same snapshot of the process
application that contains the BPD or the service that sends the message event. If
the BPD or the service of the sending message event is in a toolkit, the snapshot of
the process application (which is the root container) is used.
When the check box is selected, you are limiting the responding listener to the start
message event and to the intermediate incoming message events in that specific
process application snapshot.
Parent topic:Modeling message events
Related information:
Designating default snapshots
Adding a message event to a BPD
Attaching the undercover agent to the message event
Using intermediate message events and message end events to send messages
Creating and configuring an undercover agent for a message event

211

Using message end events


You can use a message end event when you want to send a message at an end of
a path.

Before you begin


To perform this task, you must be in the IBM Process Designer desktop editor.

About this task


For example, you might want to send a message to be received by the Start event in
another process or processes. When including message end events in a business
process definition (BPD), you should be aware of the general information that
applies to all types of message events covered in Modeling message events.

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

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.
Important: Ad hoc actions are deprecated in version 8.5.5.0, instead use Creating
an unstructured (ad hoc) activity.
If you want to enable end users to perform an ad hoc action during the execution of
another process, you can do so by using a start ad hoc event in your BPD. For
example, you may want to enable end users to cancel an order, determine the
status of an order, or perform some other ad hoc function during the normal
processing of an order. Because an ad hoc action is run in the context of the regular
process instance, it has access to all the data of the regular process instance and
can also manipulate the flow of the regular process instance, depending on the logic
that you include.Important: Process Portal users who perform ad hoc actions must
be assigned to the security group that is configured for the
ACTION_INJECT_TOKEN policy. Modify the security properties of the
BPMActionPolicy configuration object as described in Security configuration
properties.

- Building a sample ad hoc action (deprecated)


This example shows how to model an ad hoc action that enables users to view the
contents of a requisition at any time during normal processing of the requisition.
- Testing a sample ad hoc action (deprecated)
Use IBM Process Designer to test the sample ad hoc action.
Parent topic:Modeling events
Related information:
Configuring access to Process Portal action policies
Deprecated: Defining ad hoc actions

213

Building a sample ad hoc action (deprecated)


This example shows how to model an ad hoc action that enables users to view the
contents of a requisition at any time during normal processing of the requisition.

Before you begin


To perform this task, you must be in the IBM Process Designer desktop editor.

About this task


For the following example, you can use the Standard HR Open New Position
business process definition (BPD) included in the Hiring Sample process
application. (If you do not see the Hiring Sample process application in your list of
applications in the Process Center Console, ask your IBM Business Process
Manager administrator to give you access.) To do so, clone a snapshot of the Hiring
Sample process application so that your changes do not affect other users of IBM
Process Designer.

Procedure
1.
2.
3.
4.

Open the Process Designer desktop editor.


Open a BPD in the Designer view and click the Diagram tab.
Drag a swimlane from the palette to the diagram.
Right-click the new lane and select Move Lane Down until the new lane is the
last lane in the BPD (below the System lane).
5. Click the new lane in the diagram (named Untitled 1 by default) and in the
Name field in the properties, type Ad hoc event .
6. Drag a start event from the palette onto the BPD diagram so that it is positioned
in the new Ad hoc event lane.
7. In the text box that displays over the start event , type Show Requisition Data
for the event name.
8. Click the Implementation tab in the Properties view and select Ad Hoc from the
available start event types. If you wanted to restrict the users who can perform
the action, you could also associate a specific team with the swimlane and then
in the Event Visibility section specify that the event visibility is restricted by
swimlane.
9. Drag an activity from the palette into the Ad hoc event lane.
10. In the text box that displays over the user task,, type Show Data for the user task
name.
11. Drag an end event from the palette onto the BPD diagram so that it is positioned
after the Show Data activity in the Ad hoc event lane and optionally name the
end event.
12. Using the Sequence Flow tool, connect the Show Requisition Data start
event, the Show Data activity, and the end event on the BPD diagram.
13. Right-click the Show Data activity and select Activity Wizard from the list of
options.

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

Testing a sample ad hoc action (deprecated)


Use IBM Process Designer to test the sample ad hoc action.

Before you begin


To perform this task, you must be in the IBM Process Designer desktop editor.
Before you can test the sample ad hoc action, you must have a business process
definition (BPD) that contains an ad hoc event and at least one task connected by
sequence flow. For example, you can modify the Hiring Sample BPD to contain an
ad hoc action as described in Deprecated: Building a sample ad hoc action.

Procedure
1.
2.
3.
4.

Open the Process Designer desktop editor.


Open a BPD in the Designer view.
Click the Run icon in the upper right corner of the BPD diagram.
IBM Process Designer switches to the Inspector where you should see a new
Submit requisition task in the task list.
5. Open IBM Process Portal and log in as a member of one of the teams who
receive and can complete the tasks generated by the activities in the BPD.
6. Run the Submit requisition task displayed in your Open Tasks view in IBM
Process Portal.
7. Fill out the Job Requisition information, click Next, and then Submit on the
Confirm Job Position form.
8. When the next task for the process instance (Approve/reject requisition)
displays in your Open Tasks view in IBM Process Portal, click the instance
name or task subject to open the details page. Note: If the task does not display,
reload the browser page.
9. Click the Actions menu in the toolbar, and select the name of the ad hoc action.
(The name of the action is the name that you assign the ad hoc event that
initiates the user task in the BPD diagram in IBM Process Designer. If you are
using the modified Hiring Sample, the name is Show Requisition Data. )IBM
BPM generates a new task called Show Data, which is displayed in your Open
Tasks view.
10. Run the Show Data task. If you receive an information message about claiming
the new task, click Claim Task. IBM BPM displays the data that you entered in
step 5.
11. Click OK.Now you can continue with normal processing by completing the next
task in the process instance, Approve/reject requisition. You can invoke
the ad hoc action again, after completion of the Approve/reject requisition
task, to see whether the requisition has been approved.

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.

Parent topic:Enabling users to perform ad hoc actions (deprecated)

216

Related information:
Getting started with Process Portal
Configuring access to Process Portal action policies

217

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.

Before you begin


To perform this task, you must be in the IBM Process Designer desktop editor.

About this task


An event gateway represents a branching point in a process execution where only
one of several paths can be followed, depending on events that occur. A specific
event, such as the receipt of a message or timer event, determines the path that will
be taken. The event gateway represents a single point of behavior that is spread out
across multiple process components connected by sequence flow. The following
types of events can directly follow an event gateway (connected by a single
sequence flow):
- Intermediate message event (receiving)
- Intermediate timer event
When creating an event gateway, you must connect at least two intermediate events
to the gateway. And, when connected to an event gateway, an intermediate event is
not allowed to have additional incoming sequence flow.

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

Parent topic:Modeling events

219

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.
When you develop an application in IBM BPM, build error handling into BPDs and
services to do the following things:
- To detect errors.
- To specify how errors are thrown and caught in your runtime environment.
- To recover in a predictable manner.
For example, if a BPD involves filling orders, an item might be out of stock during
one instance of the BPD, which causes an error. Error handling that you build into
the BPD could create notifications to replenish items that are out of stock.
There are three types of error events:
- Error end events in BPDs and services that throw errors
- Error intermediate events in BPDs and services that catch errors
- Error start events in BPD event subprocesses that catch errors
You can assign error codes and error data to errors that are thrown by the error end
events.
To catch errors using error intermediate events, select an error code from a list of
previously defined errors and map the error data to a variable. The error
intermediate events are boundary events, which are intermediate events that are
attached to the boundary of an activity. Each boundary event can be triggered only
while the activity is running, interrupting the activity. From the BPD diagram or a
service diagram in Process Designer, you can use an error intermediate event that
is attached to the boundary of an active to catch specific errors and error data from
a linked process, a subprocess, or a service.
Another way to catch errors is by using error intermediate events in services that
catch all errors. When building services, you can attach an error intermediate event
to the boundary of a step to catch all errors for the step, and you can use an error
intermediate event as part of the service flow to catch all errors that are raised by
steps of the service flow that are not handled by an error intermediate event at the
boundary of the step.
You also can catch errors using error event subprocesses in BPDs. In the
subprocess, you use an error start event that catches errors if the start event is
triggered.
However you decide to catch errors, designate the error behavior for the events on
the Properties tab in your diagram. Under Implementation, go to the Error
Properties section to designate the following error handling behavior:
- Catch all errors or specific errors. To catch specific errors, you can select the error
code, map the error data, or both, as described in the following bullets.
- Filter the specific errors that are caught by selecting an error code from a list of all
thrown errors for the linked process, subprocess, or service.
- Map the error data into a variable by selecting an error mapping variable that was
previously defined on the Variables tab. Important: If the error code has changed,
make sure to select the variable again so that it is mapped properly.
If there are multiple error events defined to catch errors for an error that is thrown in

220

a linked process, subprocess, or service, the catching event is determined by the


precedence rules in the order that they are listed in the Error event components
table.
Errors are caught in the following order in your runtime environment:
1. The boundary events catch errors that are raised by the attached activity, as
described in the following table.
2. If there is no error boundary event that handles the error, and a subprocess is in a
BPD or in an unattached intermediate error event in a service, errors are caught
in the error event subprocesses, as described in the following table.
3. If there is no error event subprocess that handles the error in an event
subprocess, linked process, or service, errors are propagated to the next level.

Table 1. Error event components


Specify
error code and error data
error code
error data
neither code nor error data
or
the Catch All Errors option on error
properties

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

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.
Table 1. Usage of error events in business process definitions
BPD event

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

Catching errors using error intermediate events


For BPDs, you can attach an error intermediate event to an activity and connect that
event to an error handling flow or activity. The attached error event is known as a
error boundary event.
To determine whether to use error immediate events, consider the following points:
- If an error occurs while a process is running an activity with an attached error event
at the boundary, the process flows along the sequence line that is attached to the
error event. Errors are handled in the flow and then proceed with the normal
processing.
- Error intermediate events must be attached to an activity.
- You can have multiple error events for an activity, but only one catches the error.
- Consider specifying the error data 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. 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.step.error
variable.

Catching errors using error event subprocesses


An event subprocess is a specialized type of subprocess that is not part of the
normal sequence flow of its parent process. An error event subprocess is an event
subprocess that contains an error start event. The event subprocess is not
connected by sequence flow and runs only if the start event in the event subprocess
is triggered. You can use error event subprocesses to handle errors in your BPD.
To determine whether to use error event subprocesses, consider the following
points:
- Define a readable process by locating the error event in the event subprocess
instead of defining it in the process.
223

- 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.

Parent topic:Handling errors using error events

224

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.
Table 1. Usage of error events in services
Service event
error intermediate event
attached to
the boundary of a step (error boundary
event)
error intermediate event
service flow

error end event

Description
Catches errors from the step

as part of the Catches all errors raised by steps of the


service flow that are not handled by an
error intermediate event at the boundary
of a step. This event can have only
outbound links.
Throws an error and ends the processing
of this service. You might, for example,
use an error end event when you want a
particular result from a Coach to end a
human service.

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.

Using error intermediate events in the service flow


The use of error intermediate events in a service flow offers several options in error
handling, but it must be done carefully to prevent unexpected behaviour.
An error intermediate event in the service flow can act as a global error handler in
the service. It catches errors that are not already handled by boundary error events.
The error intermediate event cannot catch specific errors; it is a catchAll error event.
It is meant for handling errors that can be handled within that very service flow. It is
recommended that you not wire back into the normal flow. Instead, after the error
handling, logic should be concluded with an end event. After the error handling you
225

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>

</execution-context> <!-- insert if not already present -->


</server> <!-- insert if not already present -->

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.

Parent topic:Handling errors using error events

226

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.
Models that were created in V7.5.x and earlier versions include the following errorhandling behavior:
- Error intermediate events at the boundary of a step in services or at the boundary
of an activity in a business process definition (BPD), subprocess, or event
subprocess catch all errors. As of V8.0, you model this behavior using the Catch
All Errors option, which is available on the Properties tab for a catching error
event. In addition, you can refine your error handling by catching specific errors
using the Catch Specific Errors option.
- Error intermediate events in the flow of a BPD, subprocess, or event subprocess
were allowed but had no effect on runtime behavior. You can delete these events.
- Error end events in services, BPDs, subprocesses, or event subprocesses retain
the same error throwing behavior: they can be caught only as part of an event that
catches all errors. To use the extended error-handling capabilities, delete the old
event and add a new event.
To use the latest error-handling capabilities, you can move the models to V8.0.
Open your application, look at the referenced system toolkits, click a toolkit, and
select the menu option to upgrade it.
Parent topic:Handling errors using error events

227

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.
You can also use SCA to create a BPD instance without the use of a receiving
message event. In that scenario, the inputs of the BPD and optionally its outputs
define the service interface for the SCA interaction. To interact with receiving
message events, you can use SCA as the triggering mechanism as an alternative to
using undercover agents (UCA). A receiving message event can be a start message
event, intermediate message event, boundary message event, or the start event of
an event subprocess.
The use of SCA as the triggering mechanism makes it possible to use instancebased correlation that always delivers the message to exactly one event of one
instance. By contrast, correlation that is supported by undercover agent invocations
permits multiple instances and events (of the same or different models) to receive
the same message.

Supported interaction patterns that use receiving message


events
You can use SCA messages to invoke the following BPD event types. These
interactions are one-way interactions.
- Message Start Event
- The start event causes a new instance of the BPD to be created. If your BPD
includes more than one start event, each one should use a different SCA
service identifier. Otherwise, if multiple start events specify the same SCA
service identifier, the start event that receives the start message is selected
arbitrarily.
- Start Event of a Message Event Subprocess
- The Start Event of a Message Event Subprocess requires correlation. A
message that invokes a message event subprocess must be correlated with the
BPD instance that then invokes the event subprocess. Optionally, this event
type can be configured to be repeatable or to interrupt the parent process
instance.
- Intermediate Message Event
- An intermediate message event requires correlation to ensure that the message
triggers the intermediate message event that belongs to the correct BPD
instance.
- Boundary Message Event
- A boundary message event is an intermediate message event that is attached
to an activity. A boundary message event requires correlation to ensure that the
message triggers the boundary message event that belongs to the correct BPD
instance. Optionally, this event type can be configured to be repeatable or to
interrupt the activity that the event is attached to.

228

Supported interaction patterns that use input and output


variables
The input and output variables of the BPD define the parameters of the SCA request
message and SCA response message. They are used to store the parameter data
of the request message and the response message that are exchanged by means of
SCA. There are two interaction patterns:
- One-way interface
- You create a BPD instance using the one-way interface of the BPD. The
message parameters are automatically assigned to the input variables when
the BPD instance receives the SCA message.
- Request-response interface
- You create a BPD instance and upon the completion of the BPD, you receive a
response message that uses the request/response interface of the BPD. The
request message parameters are automatically assigned to the input variables
when the BPD instance receives the SCA request message. The SCA
response message is constructed from the output variables when the BPD
instance ends.
The one-way interface and the two-way interface are derived from the input and
output variables. Both interfaces are available in IBM Integration Designer for use
as an SCA module.

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.

Defining a service that can trigger different events in a BPD


In general, when receiving message events are used with SCA, the corresponding
service interfaces of the BPD are derived from the message event's service
identifier and message object type.
229

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.

Rules for instance migration


To allow instance migration of BPDs that contain SCA message events and
variables that are marked as process instance identifiers, you must conform to the
rules for what cannot be changed or deleted when you create a new version of a
BPD that is already deployed. The rules are described in Strategies for migrating
instances.

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

arrive for the instance.


C. Optional: Add a start message event to your process. See Using start
message events.
D. If you want message event subprocesses or receiving message events in a
process to be able to receive SCA messages:
1. Add intermediate receiving message events and boundary message events
as necessary. See Using intermediate and boundary message events to
receive messages.
2. Add a message event subprocess, with a corresponding start message
event where required. See Using start message events.
3. For each receiving message event, as a part of the data mapping, select the
variable that uniquely identifies each process instance. See Mapping input
and output data for an activity or step.
2. Switch to using IBM Integration Designer, and complete the following actions:
A. Drag the BPD onto the design canvas, and select which interfaces to include in
the SCA import. See Creating an import to start a business process definition.
B. In the assembly editor, you can use the SCA import to invoke and
communicate with a BPD instance using SCA messages.

Parent topic:Modeling events

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

Attaching the undercover agent to the message event

233

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.

Before you begin


To perform this task, you must be in the IBM Process Designer desktop editor.

About this task


See Building a sample inbound integration to learn how to build a sample integration
that includes this type of undercover agent.

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

Forces one job to finish before the next


job can start. By default, three
synchronous queues are available.

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

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.

Before you begin


To perform this task, you must be in the IBM Process Designer desktop editor.

About this task


Scheduled undercover agents do not run on the Process Center server unless you
click Run Now. If you are testing a business process definition (BPD) that includes
scheduled undercover agents, and you want to ensure that the undercover agents
run on time, run the BPD on a Process Server in one of your runtime environments,
such as your development, test or staging environment.

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

Forces one job to finish before the next


job can start. By default, three
synchronous queues are available.

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

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.

Before you begin


To perform this task, you must be in the IBM Process Designer desktop editor.
The following procedure describes how to create a content undercover agent
without consideration for some of the other components that are required to detect
and respond to ECM events, such as an event subscription. If you need to create a
content undercover agent and all of the other required components as well, you
should follow the instructions in the topic Subscribing to document and folder
events: the end-to-end approach. This end-to-end approach is a simpler approach
than creating each component on a stand-alone basis. It automatically creates some
resources that you would otherwise need to create manually.

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.

Parent topic:Undercover agents


Parent topic:Performing modeling tasks for inbound events

241

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.

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.

- Linking to external information


To include a link to an external source, paste a link into the Description field of the
process application or toolkit, or the Documentation field of an artifact in IBM
Process Designer.
- Process documentation location links
When you work with process applications and toolkits in IBM Process Center or
IBM Process Designer, you can share the location of an artifact in your
development flow by copying a link to that artifact.
Parent topic:Modeling processes

242

Linking to external information


To include a link to an external source, paste a link into the Description field of the
process application or toolkit, or the Documentation field of an artifact in IBM
Process Designer.
When you work with process applications or toolkits, you might need to link to
related information that is outside of the IBM Business Process Manager
environment. For example, you might want to link to a website or a wiki page. You
can also reference a change request stored in a change management system or a
test case in a quality management system. These kinds of links can be used to
achieve traceability or provide details about the fixes and features that went into a
new process application snapshot.
Parent topic:Documenting development artifacts

Adding a link
You can add a link to an external resource in a process application or toolkit
description.

Before you begin


To add a link in the documentation field in IBM Process Designer, you must use the
Process Designer desktop editor.

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

Editing an existing link


When you have your link setup, you might need to update the link or change it to a
new link.

Before you begin


To edit a link in IBM Process Designer, you must use the Process Designer desktop
editor.

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

Process documentation location links


When you work with process applications and toolkits in IBM Process Center or
IBM Process Designer, you can share the location of an artifact in your development
flow by copying a link to that artifact.
You might need to provide a link to an artifact, such as a business process definition
(BPD), outside of IBM Business Process Manager. For example, you might want to
email the Process Center location of a BPD or a process application. Perhaps you
might need to share a link to an artifact within another artifact, such as by sharing a
link to a process application in the documentation of another process application.
Parent topic:Documenting development artifacts

246

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.
To use an external implementation to implement an activity in a business process
definition (BPD), complete the tasks listed in this section.
Tip: In product releases older than V7.5.1, external implementations were referred
to as external activities.

1. Building a custom application to implement an activity


Build a custom application using the IBM Business Process Manager Web API to
implement an activity in a BPD.
2. Creating an external implementation
Create an external implementation when you want to reuse an existing external
application or create an external application to handle one or more steps in your
process.
3. Using an external implementation to implement an activity
Select a custom application to implement a particular activity (step) in a BPD.
Parent topic:Modeling processes

247

Building a custom application to implement an


activity
Build a custom application using the IBM Business Process Manager Web API to
implement an activity in a BPD.
If you want to build a custom application to implement an activity within a process,
you must use the IBM Business Process Manager Web API to enable your custom
application to interact with IBM BPM. For example, the IBM BPM Web API provides
operations that enable you to pass variables from an IBM BPM BPD to a custom
application and then back to the BPD for continued processing.
Using the IBM BPM Web API sample external implementation
IBM Business Process Manager includes a sample external implementation that
illustrates how to use IBM BPM Web API operations when developing a custom
application to enable process participants to complete a particular step within a
process. The IBM Process Designer enables you to include these custom
applications in your Business Process Definitions (BPDs) and model them as
external implementations.
The Samples Exchange on Blueworks Live includes a sample external
implementation. The sample external implementation is a custom Eclipse application
that enables managers to either approve or reject expense reports from their
employees. It represents one step in a process and can be modeled as an external
implementation in IBM Process Designer.
Download the samples archive file from Sample Exchange Home. Search using
keywords web-api.
If you import the BPD External Implementation Library and other associated
components in the ExpenseApproval.twx file from the sample, the Eclipse
application, combined with the corresponding library items, is a complete working
example of external implementations.

Parent topic:Using external implementations


Next topic:Creating an external implementation
Related concepts:
Web API and external implementations

248

Creating an external implementation


Create an external implementation when you want to reuse an existing external
application or create an external application to handle one or more steps in your
process.

Before you begin


To perform this task, you must be in the IBM Process Designer desktop editor.

About this task


Using the external implementation function is similar to using the service functions
like an integration service or web service. However, unlike those service functions
that are designed for a specific area like web services or integration, the external
implementation is more generic in nature. When a step in a business process is
implemented with an external implementation, the business process halts and waits
for input from the external application.
To create an external implementation, use the Web APIs or REST APIs. The
previous topic discusses a sample that creates an external implementation with the
Web APIs. To create an external implementation with the REST APIs, these articles
are helpful. Using the REST APIs in IBM Business Process Manager and
Integrating a business process application with an external system using the REST
API. The related links at the bottom of this topic link to more information on the Web
APIs and REST APIs.
When you create an external implementation in IBM Process Designer, you need to
know the properties to use to identify and run the custom application. If you did not
build the custom application, you need to coordinate with the developers to ensure
that you provide the appropriate properties in IBM Process Designer.

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.

Parent topic:Using external implementations


Previous topic:Building a custom application to implement an activity
Next topic:Using an external implementation to implement an activity
Related concepts:
Using the web service API in IBM BPM
Related information:
Developing client applications that use IBM BPM REST APIs

250

Using an external implementation to implement an


activity
Select a custom application to implement a particular activity (step) in a BPD.

Before you begin


To perform this task, you must be in the IBM Process Designer desktop editor.

About this task


The following steps describe how to select a custom application as the
implementation for an activity in a BPD:

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

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.
IBM Business Process Manager supports both outbound and inbound integration
as described in the following table:
Table 1. Supported integration types
Integration type
Outbound

Inbound

Description

Required IBM BPM


components
IBM BPM communicates
Integration service, IBM
with an external system to Case Manager Integration
retrieve, update, or insert Service, or Undercover
data.
Agent
An external system calls
Undercover Agent and
into IBM BPM to initiate a Web Service
service.

- Creating outbound integrations


Outbound integrations enable business process authored in Process Designer to
interact with other systems, such as a web service, a content management system,
or an external database. Depending on the system that you are integrating with,
you can implement the integration service using an Integration Service
implementation or an IBM Case Manager Integration Service implementation.
- Creating inbound integrations
For inbound integrations that involve an external system or application calling into
IBM Business Process Manager to kick off a service, you need to build several
IBM BPM components and corresponding services.
- Web services compatibility
Web services conform to a flexible architecture that allows variation in web
services implementations. This variation unfortunately can lead to compatibility
problems.
Parent topic:Modeling processes

253

Creating outbound integrations


Outbound integrations enable business process authored in Process Designer to
interact with other systems, such as a web service, a content management system,
or an external database. Depending on the system that you are integrating with, you
can implement the integration service using an Integration Service implementation
or an IBM Case Manager Integration Service implementation.
To create an outbound integration with an external database, use the predefined
SQL Integration services that are available in the IBM BPM System Data Toolkit.

Integration Service implementations


Integration Service implementations can contain integration step types that you can
configure for the system that you are interacting with. For example, a Web Service
Integration step is useful if you are not passing volumes of information. A Java
Integration step gives you access to the features of the Java language, including
published Java libraries and APIs. The following table describes the integration step
types that are available for Integration Service implementations.
Table 1. Step types that can be used in an Integration Service implementation
Integration step type
Web Service Integration

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).

IBM Case Manager Integration Service implementations


An IBM Case Manager integration service is the means of accessing case
management cases from a business process both for searching and updating case
254

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..

- Creating outbound integrations to web services


Integration services enable outbound integration with web services so that
processes can retrieve and update data that is stored on an external system. You
can use a generic web service connector or a Web Service Integration step to
enable the access to the web service.
- Calling a Java method in an integration service
If the implementation for an activity requires calling methods from a Java class,
you can use the Java Integration step in an integration service.
- Sending attachments using an SMTP server
With a Java Integration component, you can send attachments by using a Simple
Mail Transfer Protocol (SMTP) server.
- Using IBM Business Process Manager SQL Integration services
To integrate with an external database, you can use the SQL Integration services
available in the IBM BPM System Data Toolkit.
Parent topic:Integrating with web services, Java and databases
Related information:
Building an Integration service
Integrating with Enterprise Content Management (ECM) systems
Integrating BPDs with IBM Case Manager cases
Undercover agents
Using IBM Business Process Manager SQL Integration services

255

Creating outbound integrations to web services


Integration services enable outbound integration with web services so that
processes can retrieve and update data that is stored on an external system. You
can use a generic web service connector or a Web Service Integration step to
enable the access to the web service.
A generic web service connector, Call WebService via SOAP, is provided in the
System Data Toolkit. This connector abstracts the complexity of the web service
implementation and requires only minimal configuration. For more information on
using the connector, see Calling a web service using a SOAP connector.
However, if you have specific requirements on the web service, such as the type of
security or message encryption, use a Web Service Integration step to integrate with
the service.
- SOAP headers
Use a SOAP header to include application-specific context information in the web
service SOAP request and response messages.
- Creating implicit SOAP headers for outbound web service integrations
SOAP headers are used to communicate application-specific context information
within SOAP request and response messages. This context information can be
anything that you need to send along with the web service operation parameters.
An implicit SOAP header is one that is not defined in the web service WSDL
document. As part of your outbound web service integrations, you can add implicit
SOAP headers to your web service request messages and retrieve SOAP headers
from response messages.
- Adding a web services server
You can add one or more web services servers to your process application. Each
web services server describes the location of a web service endpoint and can be
referenced when you define an outbound web service integration. This reference
enables the sharing of configuration information between web service integrations
that starts the same endpoint, eliminating the need to configure similar information
multiple times. In addition, if you need to change the information that is associated
with a particular endpoint, you can change the web services server information and
the updated information can be used by any web service integration that
references the web services server.
- Configuring a Web Service Integration component
Use a Web Service Integration component to invoke a web service that is hosted
externally. You can configure the WSDL properties, SOAP header information,
authentication, signature and encryption properties for the web service integration.
- Security for Web Service Integration steps
You can secure a web service using policy sets and bindings or by manually
creating an authentication method that requires a user name and password.
- Web service faults
Faults are a way of handling exceptions in web services at run time. A fault that
helps a user understand a problem and what he can do about it leads to a quick
resolution of the problem. If you use a Web Service Integration step from the
integration service palette to call an outbound web service, your step can catch

256

and handle faults.


- Serialization of IBM Business Process Manager objects for use in web
services
You can add metadata to IBM BPM objects to control how those objects are
serialized into XML elements in a SOAP request for web services.
- Setting up message-level encryption
Message-level encryption provides confidentiality by applying encryption to all or
parts of a SOAP message. The encryption spans the entire communication chain
between the consumer and the provider. To take advantage of this type of
encryption in integration services for BPDs, you must enable the corresponding
configuration settings.
- Troubleshooting web services outbound web service integrations
Learn how to solve problems that you may have when using web service
integration steps in your services.
- Considerations when using WSDL with multiple XSD or WSDL imports
When you are using Web Services Description Language (WSDL) with multiple
XSD or WSDL imports for an outbound web service component, you can merge all
of your XSDs into one WSDL file to avoid multiple connections to your endpoint.
- Troubleshooting XML schema messages for web service integrations
When you are using a Web Service Integration component, you might encounter
error and warning messages if you use XML constructs that are not supported or
have problems in Process Designer.
Parent topic:Creating outbound integrations
Related information:
Building an Integration service
Supported web service standards

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.

Parent topic:Creating outbound integrations to web services


Related information:
Creating implicit SOAP headers for outbound web service integrations
Retrieving SOAP headers from the SOAP response message

259

Creating implicit SOAP headers for outbound web


service integrations
SOAP headers are used to communicate application-specific context information
within SOAP request and response messages. This context information can be
anything that you need to send along with the web service operation parameters. An
implicit SOAP header is one that is not defined in the web service WSDL document.
As part of your outbound web service integrations, you can add implicit SOAP
headers to your web service request messages and retrieve SOAP headers from
response messages.

About this task


Note: The Headers tab in the Properties view for web services is deprecated. The
method for adding implicit SOAP headers described here is now the preferred
method.
All the variables that you declare in IBM Process Designer are JavaScript
variables. You can use them inside service definitions and also in expression
evaluations inside JavaScript code snippets.
- Adding SOAP headers to a SOAP request message
You can add a SOAP header to a request message by creating a variable of type
SOAPHeader or SOAPHeaders. You can then map that variable to the SOAP header
request.
- Retrieving SOAP headers from the SOAP response message
You can retrieve SOAP headers from a response message by creating a variable
of type SOAPHeaders and then mapping that variable to the SOAP header
response.

Parent topic:Creating outbound integrations to web services


Related information:
Using JavaScript variables and objects inside Process Designer
SOAP headers

260

Adding SOAP headers to a SOAP request message


You can add a SOAP header to a request message by creating a variable of type
SOAPHeader or SOAPHeaders. You can then map that variable to the SOAP header
request.

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>";

// Initialize the "auditLogUUID" header


var header2 = new tw.object.SOAPHeader();
header2.name = "auditLogUUID";
header2.nameSpace = "http://acme.com";
header2.value = "<x:auditLogUUID xmlns:x=\http://acme.com\">ab74-ffce-3333-feab</x:auditLogUUID>";

// Now add the two headers to the SOAPHeaders variable


tw.local.requestHeaders.headers[0] = header1;
tw.local.requestHeaders.headers[1] = header2;

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

Retrieving SOAP headers from the SOAP response


message
You can retrieve SOAP headers from a response message by creating a variable of
type SOAPHeaders and then mapping that variable to the SOAP header response.

Before you begin


This task requires that you have access to an integration service with a web service
integration component and a SOAP request message.

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];
}
}

5. Complete the definition of the web service integration.


6. Run the integration service by clicking Run Service and verify that the SOAP
headers are added to the request message and that the expected SOAP headers
are retrieved from the response SOAP message.
Parent topic:Creating implicit SOAP headers for outbound web service integrations
Related information:
Adding SOAP headers to a SOAP request message for an outbound web service

263

Adding a web services server


You can add one or more web services servers to your process application. Each
web services server describes the location of a web service endpoint and can be
referenced when you define an outbound web service integration. This reference
enables the sharing of configuration information between web service integrations
that starts the same endpoint, eliminating the need to configure similar information
multiple times. In addition, if you need to change the information that is associated
with a particular endpoint, you can change the web services server information and
the updated information can be used by any web service integration that references
the web services server.

Before you begin


To perform this task, you must be in the IBM Process Designer desktop editor.
Also, the policy set and bindings must be configured by a system administrator.

About this task


The web services server can be configured with policy sets and bindings. Policy sets
simplify the configuration of web services by providing reusable configurations. A
web services policy set defines a set of configuration properties to be associated
with a web service integration or endpoint. A policy set follows the WS-Policy
specification. One example of how policy sets can be used is to configure WSSecurity for your web service endpoint or outbound web service integration. WSSecurity provides SOAP message-layer security with the following tokens and
elements:
- Security tokens: Security tokens contain authentication information that flows with
the message.
- Signature elements: Digital signature information for all or part of the message
verifies that the original request is not modified.
- Encryption elements: Messages can be encrypted, either completely or partially, so
that only the intended recipient can read it.

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

5. Beneath the Server Locations heading, enter the following information:


- Environment Type: The environment of the web service server. Add 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. 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.
- WSDL URL: The URL of the web service. For example:
http://mycorporation.com/webservice/financialstatements?wsdl. You
can enter a URL or browse to retrieve a URL.
- Select Browse to launch the Registry Explorer.
A. Select a registry type from the list and select a registry URL or enter a new
one.
B. For protected services, click Is Protected and enter a userid and password.
Click Next.
C. Enter the name of the web service and click Search services. You can
include wildcard characters in the name. For a Universal Description
Discovery and Integration (UDDI) registry use the percent sign (%) and for a
WebSphere Service Registry and Repository (WSRR) registry use an
asterisk (*).
D. Select a web service, click Next to see the detailed information and then
click 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 provide the other information about the WSDL file.
You can use text in the fields or text that is wrapped by <# ... #> control
characters; that is, as JavaScript code.
- Select View to view the WSDL source code of a WSDL file.
- Select Discover to verify that the URL is correct. The Discovery Status field
shows Successfully Discovered.
- Discovery Status: Confirms if you have made a connection to the server and
successfully read the WSDL file.
- Override Endpoint: If selected, you can override the WSDL URL field using the
fields beneath the check box. This selection can be useful if you use different
endpoints for development and testing, for example.
- Endpoint Address: The URL of the web service you want to use. You can use
the same format as the WSDL URL field that you are overriding.
- Port: If there are multiple ports that are defined in the WSDL file and there is a
specific port for the web service that you want to use, then enter the port name
in this field.
265

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

Parent topic:Creating outbound integrations to web services


Related information:
Configuring a web service server at run time
Supported web service standards
WS-Security specification

267

Configuring a Web Service Integration component


Use a Web Service Integration component to invoke a web service that is hosted
externally. You can configure the WSDL properties, SOAP header information,
authentication, signature and encryption properties for the web service integration.

Before you begin


If the web service uses the SSL protocol, the certificate that is used by the target
host must be installed in the IBM BPM environment as described in Secure
communications using SSL. If the certificate is not installed, you get a No trusted
certificate is found error when you try to discover the WSDL implementation
properties.
Ensure that you know whether the service that you are invoking requires any
additional SOAP headers in web service messages. Conversely, if the web service
has to process the request message, for example, for the security information,
contact the web service provider to ensure that they can support your header.
If the web service uses X509 client and server certificates for both encrypting and
signing the request, the certificates must be added to the IBM Business Process
Manager keystore. In addition, configuration changes must be made to the
100Custom.xml file as described in Setting up message-level encryption.
The 99Local.xml file sets the use-jaxws property to true. In most cases this
setting is appropriate for an integration with a web service as many web services
use the Java API for XML Web Services (JAX-WS). If the web service you are
integrating with, however, uses a Remote Procedure Call (RPC) encoding style then
you should set the use-jaxws property to false.

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

Security for Web Service Integration steps


You can secure a web service using policy sets and bindings or by manually
creating an authentication method that requires a user name and password.
To use policy sets and bindings, see the following topics:
- Configuring a Web Service Integration component
- Adding a web services server
- Creating an inbound web service
In the context of web service integration with BPDs, security can be required at
design time and at run time.

Design time authentication


If you are manually creating your own security, at design time you can enable
protected WSDL in the implementation properties for the Web Service Integration
step and provide the user name and password.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://.

Run time authentication


If you are manually creating your own security, authentication options for SOAP
calls at run time are available in the security properties for the Web Service
Integration step. The following table describes the information that you must provide
for each supported option:
Table 1. Input required for authentication options
Option
HTTP basic authentication

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

Username token authentication

When using username token


authentication in IBM BPM, a user name
and password are passed to a web
service in the SOAP header of the SOAP
request. Username token authentication
allows for different algorithms and
formats for passing the password.
IBM BPM supports passwords in plain
text and digest format. The specification
for username token authentication
describes two optional elements that can
be supplied: wsse:Noncewsu:Created
The IBM BPM implementation of this
standard always provides wsse:Nonce
and wsu:Created. This is compatible
with the behavior of Microsoft WSE 2.0
Toolkit when using username token
digest authentication.
For more information, see Web Services
Security UsernameToken Profile 1.0.

Parent topic:Creating outbound integrations to web services


Related information:
Supported web service standards

272

Web service faults


Faults are a way of handling exceptions in web services at run time. A fault that
helps a user understand a problem and what he can do about it leads to a quick
resolution of the problem. If you use a Web Service Integration step from the
integration service palette to call an outbound web service, your step can catch and
handle faults.
To catch and handle faults, attach an error intermediate event to the web service
integration. By default, configure the error intermediate event with the Catch All
Errors option to catch faults which are modeled in WSDL, as well as other faults
such as system or connectivity exceptions. For more information on handling faults,
see Handling errors in services.
Figure 1. An outbound web service integration with attached error intermediate

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.

Parent topic:Creating outbound integrations to web services


Related information:
Modeling events
Handling errors in services

274

Serialization of IBM Business Process Manager objects for


use in web services
You can add metadata to IBM BPM objects to control how those objects are
serialized into XML elements in a SOAP request for web services.
When sending complex types as input parameters to web services, IBM BPM often
needs hints as to how to structure the data. These methods are built on the structure
because a structure is, by definition, a Complex type.
Note: Serializing IBM BPM objects for use in web services is primarily for advanced
users, and is now required only when using Record objects with web services
instead of the generated types.
The following methods have been added to the tw.object.Record() object to
assist in forming the SOAP request:
- setSOAPElementName(string elementName)
- setSOAPElementNS(string namespace)
- defineSOAPProperty(string propertyName, string schemaName, string
typeName, boolean isAttribute, string namespace)

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"; #>

This generates the following XML element:


<NameUpdateRequest xmlns="http://www.lombardisoftware.com/schemas/ NameUpdateRequest"> <first xmlns="">John</first> <last
xmlns="">Smith</last> </NameUpdateRequest>

Parent topic:Creating outbound integrations to web services

275

Setting up message-level encryption


Message-level encryption provides confidentiality by applying encryption to all or
parts of a SOAP message. The encryption spans the entire communication chain
between the consumer and the provider. To take advantage of this type of
encryption in integration services for BPDs, you must enable the corresponding
configuration settings.

Before you begin


There are two ways of setting up message-level encryption. You can use policy sets
and bindings, which simplify the encryption with reusable configurations. To use
policy sets and bindings, see the following topics:
- Adding a web services server
- Configuring a Web Service Integration component
- Creating an inbound web service.
Alternately, you can configure a specific encryption using the 100Custom.xml file as
shown in this topic. First, check that the 100Custom.xml file exists. See The
99Local.xml and 100Custom.xml configuration files.

About this task


The default 100Custom.xml configuration file includes a <server> section that you
can use to set up message-level encryption for integration services.<server>
<webservice-security merge="mergeChildren">
<keystore-file merge="replace">teamworks.jks</keystore-file>
<keystore-password-encrypted>password</keystore-password-encrypted>
<private-key>
<alias>soaprequester</alias>
<keyname>soaprequester</keyname>
<password-encrypted>password</password-encrypted>
</private-key>

<private-key>
<alias>soapprovider</alias>
<keyname>soapprovider</keyname>
</private-key>
<keystore-type>JKS</keystore-type>
<certificate>path to client certificate</certificate>
</webservice-security>
</server>

Table 1. Elements in the <server> section of the default 100Custom.xml file


Element name
<keystore-file>

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>

Provide a key store


password for the service
requester.
Holds an element that
contains information about
the private key for the
client. This element has
two child elements.
Alias for the private key
specified during creating of
the key store.
Holds the key name for the
alias. If this element is not
present, specify the alias
name as the key name.
Provide the encrypted key
password for accessing the
client private key.
Provide the key store type.
This element can have one
of the following
values:JKSUse this value if
the keystore uses Java
Keystore format.JCEKSUse
this value if the Java
Cryptography Extension is
configured in the
application server.
PKCS12KS (PKCS12)Use
this value if the keystore
file uses the PKCS#12 file
format. If a type is not
provided, the default is
JKS.
Provide the client
certificate path including
the certificate file name.

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.

Parent topic:Creating outbound integrations to web services

278

Troubleshooting web servicesoutbound web service


integrations
Learn how to solve problems that you may have when using web service integration
steps in your services.
The following table describes some common problems that you might encounter
when creating services that include web serviceoutbound web service integration
steps:
Table 1. Common problems for the outbound web service integrations
Issue

Error message when you


click Discover
Incorrect WSDL URI value PARSER ERROR:
Problem parsing
'[path_name]\webAPIServi
ce.':The markup in the
document following the
root element must be well
formed.

Nonexistent host

Unknown Host Exception

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.

Authentication required for Runtime Exception:


WSDL access
Unauthorized access to
'[path_name]\webAPIServi
ce?WSDL'

The WSDL URI is


protected by an
authentication mechanism.
If you have permission to
access the web service,
check the Protected
WSDL check box, and
then enter the Username
and Password .
Navigate to the WSDL URI
using a web browser and
save the text of the WSDL
to a file so that you can
use the file location as the
target WSDL URI.

Parent topic:Creating outbound integrations to web services

280

Considerations when using WSDL with multiple


XSD or WSDL imports
When you are using Web Services Description Language (WSDL) with multiple XSD
or WSDL imports for an outbound web service component, you can merge all of
your XSDs into one WSDL file to avoid multiple connections to your endpoint.
When you are using WSDL with multiple XSD or WSDL imports for an outbound
web service component, IBM BPM creates a connection for each XSD or WSDL
import. For example, if you have 20 XSD imports defined in a WSDL file, IBM BPM
creates 20 connections to your web service to fetch the artifacts.
This happens in the following scenarios :
1. When you are discovering WSDL for the first time.
2. When you use web service integration for the first time after a server restart.
3. If the web service definition is not found in the IBM BPM runtime cache.
To avoid multiple connections to your endpoint, you can merge all of your XSDs into
one WSDL file. You can use a tool such as IBM Integration Designer (IID) to import
your WSDL, and you can choose to include all of your XSDs in that WSDL file when
you export the WSDL out of IID.
Parent topic:Creating outbound integrations to web services

281

Troubleshooting XML schema messages for web


service integrations
When you are using a Web Service Integration component, you might encounter
error and warning messages if you use XML constructs that are not supported or
have problems in Process Designer.
These errors and warnings occur when XML types that are not valid are generated
for an external web service through a Web Service Integration component. You see
these validation errors or warnings in the type generation panel of the Generate
Types wizard, where you can copy them. The panel displays each error or warning
and the exact line in the XML construct that is causing the problem. If an error
occurs, you can select the Ignore problems and continue type generation to
continue the type generation process. The following tables list the messages you
could see in the wizard and information about each message.

Error messages caused by XML constructs that are not valid


Message
The {0} complex type contains
the {1} element that has a type
of anySimpleType, which is not
supported.The {0} global
element has a type of
anySimpleType, which is not
supported.
The {0} complex type contains
attribute {1} that is without a type
or uses anySimpleType, which
is not supported.

The {0} complex type contains


anyAttribute. Attribute
wildcards (anyAttribute) are
not supported.

Description
The anySimpleType type is not
supported.To fix the error,
replace anySimpleType with an
appropriate simple type.

The type has an attribute


declaration without a type
definition, which defaults to
anySimpleType or an attribute
with anySimpleType. Attributes
of anySimpleType are not
supported. To fix the error,
assign a simple type or replace
anySimpleType with an
appropriate simple type.
Attribute wildcards permit an
extension of the content model
while providing some control to
enforce a minimal constraint.
Because wildcards are
ignored,anyAttribute is not
supported. The location of the
wildcard is in XPath format.To fix
the error, replace anyAttribute
with an appropriate attribute.

282

The {0} complex type has a


simpleContent child, which is
not supported.

Complex types allow elements in


their content to have a simple
content element. Because
simple content elements in a
complex type are ignored, the
simpleContent element is not
supported.
The {0} complex type contains
Element wild cards, which allow
an 'any' element . Element
flexibility on what is allowed in
wildcards (any) are not
the content model, are not
supported.
supported.To fix the error,
replace ANY with concrete
elements.
The {0} complex type contains
The anyType type is not
the {1} element that is directly or supported.To fix the error,
indirectly mapped to anyType,
replace anyType with an
which is not supported.The {0} appropriate type.
global element directly or
indirectly maps to anyType,
which is not supported.
The {0} complex type contains a A model group definition
group reference with maxOccurs associates a name with a model
of {1}. However, the maximum
group so that you can reuse the
value of maxOccurs is 1.
model group. However, Process
Designer has a maximum
occurrence constraint on the
maxOccurs attribute in the model
group definition.To fix the error,
change the value of the
maxOccurs attribute to 1.
The {0} complex type contains
Process Designer has a
the {1} nested model group with maximum occurrence constraint
a maxOccurs of {2}. However,
on the maxOccurs attribute in the
the maximum value of
model group definition even if
maxOccurs is 1.
the model group is nested within
other elements. To fix the error,
change the value of the
maxOccurs attribute in the
identified model group to 1.
The {0} simple type is not
A union type creates a new type,
handled. Union types are not
which is the union of two or more
supported.
simple types. Union types are
not supported.To fix the error,
replace the union type with an
appropriate simple type.

283

The {0} complex type extends


the {1} complex type. However,
the {1} type refers to xsi:type,
which is not supported and might
cause errors at run time.

If you use a derived complex


type in place of a specified base
complex type, it is assumed that
a relationship exists between the
base type definition and the
derived type. The xsi:type
annotations are ignored and only
instances of the base complex
type are created.

Warning message caused by XML constructs that have


problems
Message
The {0} complex type contains
the {1} attribute with a value of
"default", which is not
supported.The {0} complex type
contains the {1} attribute with a
value of "fixed", which is not
supported.
A type with name {0} already
exists. Type names must be
unique.

The {0} complex type contains


the element {1} of the
base64Binary type. The
base64Binary type is
transformed to String.The {0}
global element is of the
base64Binary type. The
base64Binary type is
transformed to String.The {0}
complex type contains the
element {1} of the hexBinary
type. The hexBinary type is
transformed to String.The {0}
global element is of the
hexBinary type. The hexBinary
type is transformed to String.

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

The {0} complex type contains


the element {1} of the gYear
type. The gYear type is
transformed to String.The {0}
global element is of the
gYeartype. The gYear type is
transformed to String.The {0}
complex type contains the
element {1} of the gYearMonth
type. The gYearMonth type is
transformed to String.The {0}
global element is of the
gYearMonth type. The
gYearMonth type is transformed
to String.
The {0} complex type contains
the element {1} of the
normalizedString type. The
normalizedString type is
transformed to String.The {0}
global element is of the
normalizedString type. The
normalizedString type is
transformed to String.

The gYear and gYearMonth 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 gYear and gYearMonth
types.

The rules to normalize


whitespace values are not
supported in Process Designer.
To prevent the types from having
values that are not valid in
Process Designer, their
normalized strings are converted
to strings.To remove this
warning, do not use the
normalizedString type.
The {0} complex type contains
All XML decimal numeric types,
the element {1} of type {2}, which regardless of their precision,
is transformed to Decimal. The transform to the Decimal type in
Decimal type in Business
IBM BPM. The Decimal type
Process Manager maps to
maps to the java.lang.Double
xsd:double.The {0} global
data type through xsd:double.
element is of the type {1} is
transformed to Decimal. The
Decimal type in Business
Process Manager maps to
xsd:double.
The {0} complex type contains
All XML integer numeric types,
the element {1} of type {2}, which regardless of their precision,
is transformed to Integer.
transform to the Integer type in
TheInteger type in Business
IBM BPM. The Integer type
Process Manager maps to
maps to the
xsd:int.The {0} global element java.lang.Integer data type
is of the type {1}, which is
through xsd:int.
transformed to Integer. The
Integer type in Business
Process Manager maps to
xsd:int.
The {0} complex type extends
When a complex type has a
the {1} complex type. The
base type, Process Designer
generated business object for {0} includes all the elements and
is flattened to include the
attributes from the base type to
elements and attributes that are flatten business objects that are
defined in {1}.
created from the complex type.
285

The {0} element contains the


substitutionGroup attribute,
which is not supported.

Substitution groups are ignored.


With a substitution group, you
can specify elements that can
replace another element in
documents generated from the
schema.
The {0} simple type contains the Process Designer ignores the
{1} restriction facet, which is not following XSD restriction
supported.
facets:maxInclusivemaxExclus
iveminInclusiveminExclusive
enumeration

Parent topic:Creating outbound integrations to web services

286

Calling a Java method in an integration service


If the implementation for an activity requires calling methods from a Java class, you
can use the Java Integration step in an integration service.

Before you begin


To perform this task, you must be in the IBM Process Designer desktop editor.
Before creating the Integration service, add the JAR file that contains the classes
that you need. After you add the JAR file as a server file, you can select the class
and method that you want to use for your service. If the JAR files that you need are
included in an IBM Business Process Manager toolkit, you can add a dependency to
that toolkit to access those files. See "Creating a toolkit dependency in the Designer
view" for instructions.

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

Sending attachments using an SMTP server


With a Java Integration component, you can send attachments by using a Simple
Mail Transfer Protocol (SMTP) server.

Before you begin


To perform this task, you must be in the IBM Process Designer desktop editor.
Check that your system administrator set up the SMTP server. You must know its
URL address when you complete the following procedure.

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

Using IBM Business Process Manager SQL Integration


services
To integrate with an external database, you can use the SQL Integration services
available in the IBM BPM System Data Toolkit.

Before you begin


To perform this task, you must be in the IBM Process Designer desktop editor.

About this task


During IBM BPM installation, the System Data toolkit is imported into the Process
Center repository so that each process application and toolkit that you create has
access to IBM BPM system data. The System Data toolkit includes SQL Integration
services to enable you to easily integrate with external databases.
The SQL Integration services support common database interactions, including
support for parameterized queries. In addition, these services can automatically map
query results directly into the relevant variable type. The SQL Integration services
enable you to develop implementations to:
- Read existing data from a database
- Update existing data in a database
- Write new data to a database
In addition, when passing data between IBM BPM and a connected database, the
SQL Integration services enable you to specify certain types of data (like integers,
BLOBs, and CLOBs).
Important: The SQL connector services in the System Data toolkit support local
transactions only. They do not work properly in global transactions, for example,
during deployment or in an installation service. When SQL connector services are
used in a scenario that requires a global transaction, you might receive an error
similar to the following error:java.sql.SQLException: DSRA9350E: Operation Connection.commit
is not allowed during a global transaction.
at com.ibm.ws.rsadapter.jdbc.WSJdbcConnection.commit
(WSJdbcConnection.java:1092)
at teamworks.sql.SQLExecutor.executeInTransaction
(SQLExecutor.java:111)
at teamworks.SQLConnector.executeMultiple
(SQLConnector.java:263)

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

1. Open the Process Designer desktop editor.


2. Open a process application in the Designer view.
3. Click the indicator next to the Toolkits category to see a list of toolkit
dependencies for the current process application.
4. Click the indicator next to the System Data toolkit to see its contents.
5. Click the Implementation category and then double-click one of the listed SQL
services.For example, double-click the SQL Execute Statement service to open it.
6. In the service diagram, click the Java Integration component to select it.
7. Click the Definition option in the properties to display the Java Class and method
implemented by the service.
8. Switch from the diagram view of the service by clicking the Variables tab.
9. Click an Input or Output variable to see its details, such as its type and default
values (where applicable).

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.

Parent topic:Creating outbound integrations

292

Creating inbound integrations


For inbound integrations that involve an external system or application calling into
IBM Business Process Manager to kick off a service, you need to build several
IBM BPM components and corresponding services.
See the following topics for instructions and more information:
Note: You should also refer to Modeling message events to learn how to use a
message event to represent a point in your process where an incoming message is
received from an external system.
- Building a sample inbound integration
Several components must work together to complete an inbound integration. You
can use the procedures listed in this topic to build and test a complete integration.
- Creating implicit SOAP headers for inbound web service integrations
SOAP headers are used to communicate application-specific context information
within SOAP request and response messages. This context information can be
anything that you must send along with the web service operation parameters. An
implicit SOAP header is one that is not defined in the web service WSDL
document. In an inbound web service integration, you can retrieve SOAP headers
from an incoming request message and include SOAP headers in the outgoing
response message.
- Posting a message to IBM Business Process Manager Event Manager
If you want to post a message from an external system to IBM BPM Event
Manager, you must use the message structure that is described in this topic.
- Publishing IBM Business Process Manager web services
IBM BPM can publish web services in the same way that it consumes web
services. Using a SOAP connection, external applications can call the IBM BPM
web service to initiate a particular service or set of services.
Parent topic:Integrating with web services, Java and databases
Related information:
Undercover agents

293

Building a sample inbound integration


Several components must work together to complete an inbound integration. You
can use the procedures listed in this topic to build and test a complete integration.
To implement an inbound integration in IBM Business Process Manager, you need
to build several components that work together. The following image represents the
steps required to build a sample inbound integration.
Figure 1. Steps to build a sample inbound integration

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

Adding a message event to a BPD


Start building the sample integration by adding a message event to a business
process definition (BPD).

Before you begin


To perform this task, you must be in the IBM Process Designer desktop editor.

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

Creating an attached service


Create a service to pass parameter values from the message event to the business
process definition (BPD).

Before you begin


To perform this task, you must be in the IBM Process Designer desktop editor.

About this task


The undercover agent (UCA) that you attach to the message event needs a service
to pass the parameter values from the runtime message to the BPD.
Note: For intermediate message events like the one in this sample inbound
integration, even if no parameter values are being passed from the message event
to the BPD, you must map a UCA input variable to a local variable to ensure that the
correct running instance of the BPD resumes execution upon receipt of the message
event.

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

Creating an undercover agent


Create an event-based undercover agent.

Before you begin


To perform this task, you must be in the IBM Process Designer desktop editor.

About this task


The undercover agent tells IBM Business Process Manager what service to run
when the message event is received. The message can be triggered by IBM BPM
itself or by an external system as in this example.

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

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.

Before you begin


To perform this task, you must be in the IBM Process Designer desktop editor.

About this task


After you create the UCA, you should go back to the message event in the BPD and
attach the UCA as described in the following steps.

Procedure
1.
2.
3.
4.
5.
6.

Open the Process Designer desktop editor.


Open a process application that contains a BPD with a message event.
Open the BPD that includes the message event.
Click the message event in the BPD to select it.
Click the Implementation option in the properties.
In the Message Trigger section, click the Select button next to the Attached
UCA field and pick My UCA that you created in the preceding steps.
7. Ensure that the Consume Message and Durable Subscription check boxes
are enabled. (For more information about these options, see Modeling message
events.)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.
8. Click the Data Mapping option in the properties. Notice that the Output
correlation key is automatically set to the someString variable from the UCA.
The variable is used as a correlation parameter, which allows you to correlate an
event recipient with a particular key. Note: When an event occurs, that event
must be matched against the correct instance of the process for which the event
is destined. The ability to match the event against the correct instance is called
correlation. You must specify one variable in the message event that has a value
that matches the value of the incoming event's UCA payload (the correlation
value). If there is such a match, the message is received. If not, the message is
not received, and the event continues to wait.
9. In the field next to the variable, type tw.system.process.instanceId. This
sets the value of the someString variable to the ID of the running instance,
which allows you to test the implementation in the Inspector.In this example, you
are creating a UCA that uses the current process instance ID as the correlation
parameter. For example, if you have a process application with the instance ID

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

Creating a caller service


Create a service with appropriate inputs to call the undercover agent (UCA) to send
the event.

Before you begin


To perform this task, you must be in the IBM Process Designer desktop editor.

About this task


The next step in completing this sample inbound integration is to create an
Integration service to call the UCA to send the event when the inbound web service
(that you create in the following section) is called.

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

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.

Before you begin


To perform this task, you must be in the IBM Process Designer desktop editor.

About this task


Now you need to provide a way for an external system or application to call into
IBM Business Process Manager. The recommended method for accomplishing this
is to create and publish a web service endpoint so that external applications can
initiate a particular IBM BPM service or set of services by invoking an operation on
the endpoint. By invoking a SOAP call, external applications can call the web
service.
All operations that are exposed on an inbound web service are exposed as requestresponse operations. Even an operation bound to a service that has no outputs will
be exposed as a request-response operation with no output. One-way operations
are not supported.
Tip: The endpoint address for a web service is in the following format: http://
host_name:port/[custom_prefix/]teamworks/webservices/process_app_name/[
snapshot_name/]web_service_name.tws. If you do not specify the snapshot_name in

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

Administrative Console. Deselecting a policy set also removes the policy


binding. More information on policy sets can be found in the IBM Redbook
WebSphere Application Server Web Services Guide.
- Policy Binding: Specifies the name of the general provider 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 general provider policy set bindings available on the server.
Default policy set bindings include: Provider sample and Provider sample V2.
You can also create additional policy set bindings in the WebSphere Application
Server Administrative Console. Deselecting removes the policy binding.
Note: SOAP header information is available in system variables. The
tw.system.soap.header.request variable is automatically initialized to contain
the list of SOAP header entries found in the incoming request message. You can
include JavaScript code with your inbound web service which accesses these
SOAP header entries. You can also write JavaScript code which adds SOAP
header entries to the tw.system.soap.header.response system variable. The
SOAP header entries contained in this variable are added to the outbound
response message.
9. Save your work.Limitation: Any variable with a simple type containing a restriction
element will not have the restriction element on generation of the inbound web
service.

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.

Parent topic:Building a sample inbound integration


Related information:
Supported web service standards

303

Testing the integration


Test the completed inbound integration using the Inspector.

Before you begin


To perform this task, you must be in the IBM Process Designer desktop editor.

About this task


After you build and link the input and output of the required components as
instructed in the preceding procedures, you can test the completed inbound
integration using the Inspector in IBM Process Designer and a utility such as
soapUI.

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

Creating implicit SOAP headers for inbound web


service integrations
SOAP headers are used to communicate application-specific context information
within SOAP request and response messages. This context information can be
anything that you must send along with the web service operation parameters. An
implicit SOAP header is one that is not defined in the web service WSDL document.
In an inbound web service integration, you can retrieve SOAP headers from an
incoming request message and include SOAP headers in the outgoing response
message.
- Retrieving SOAP headers from an inbound request message
You can retrieve SOAP headers from an inbound request message by writing
some JavaScript code to capture data from the tw.system.header.soap.request
system variable.
- Adding SOAP headers to an outgoing response message
You can add a SOAP header to an outbound response message by using a
system variable and some JavaScript code.
Parent topic:Creating inbound integrations

306

Retrieving SOAP headers from an inbound request


message
You can retrieve SOAP headers from an inbound request message by writing some
JavaScript code to capture data from the tw.system.header.soap.request
system variable.

Before you begin


This task requires that you have access to an inbound web service integration that
has at least one general system service associated with it.

About this task


IBM Business Process Manager provides a system variable that you can use to
retrieve SOAP headers. SOAP headers found in inbound request messages are
automatically copied to the tw.system.header.soap.request system variable. You
can write code to retrieve those SOAP headers.

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...")

var subscriptionInfoHeader = null

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.")
}

Assume that the following SOAP header is in a request message:<ns1:subscriptionInfo


xmlns:ns1="http://acme.com">1234-56-7890-fc3a</ns1:subscriptionInfo>

The following output is produced by the code in that example: Found

the subscriptionInfo SOAP

header!

Parent topic:Creating implicit SOAP headers for inbound web service integrations

308

Adding SOAP headers to an outgoing response


message
You can add a SOAP header to an outbound response message by using a system
variable and some JavaScript code.

About this task


IBM Business Process Manager provides a system variable that allows you to add
SOAP headers to an outbound response message,
tw.system.header.soap.response. You can instantiate the
tw.system.header.soap.response variable from the Variables tab above the
process diagram or in the JavaScript code.

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...")

// Create the header object


var myResponseHeader = new tw.object.SOAPHeader()
myResponseHeader.name = "sessionToken"
myResponseHeader.nameSpace = "http://acme.com"
myResponseHeader.value = "<x:sessionToken xmlns:x=\"http://acme.com\">abdf-128974-33-33-fcea-10243-7433</x:sessionToken>"

// If the response header system variable doesn't exist yet,


// then you must instantiate it
if (tw.system.header.soap.response == null) {
tw.system.header.soap.response = new tw.object.SOAPHeaders()
tw.system.header.soap.response.headers = new Array()
}

// 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

log.info("Adding new header at index: " + nextIndex)


tw.system.header.soap.response.headers[nextIndex] = myResponseHeader

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

Posting a message to IBM Business Process Manager


Event Manager
If you want to post a message from an external system to IBM BPM Event
Manager, you must use the message structure that is described in this topic.
You can use Java Message Service (JMS) to post a message to the Event
Manager. See Maintaining and monitoring IBM Business Process Manager Event
Manager to learn how the Event Manager processes incoming requests.

Understanding the message structure


The message that you post to the Event Manager must contain an event name (the
message event ID generated when you create an undercover agent) and it can
contain parameter names and values in key-value pairs. (The topic Creating and
configuring an undercover agent for a message event describes the message event
ID that you should use for the event name.) The message must be structured as
XML as shown in the following example:
<eventmsg> <!-- The process app acronym and event name are required: The snapshot and UCA name are optional --> <event
processApp="[acronym]" snapshot="[snapshot_name]" ucaname="[UCA_name]">[event_name]</event> <!--Optional: The name of the
queue for the event to run in--> <queue>[queue name]</queue> <!--Any parameters the UCA may require-- <parameters>
<parameter> <key>param1</key> <value><![CDATA[value1]]> </value> </parameter> </parameters> </eventmsg>

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.

Passing complex variable types to undercover agents


You can use undercover agents to instantiate services and BPDs automatically,
without human interaction by an IBM BPM participant. When you include a message
event in an IBM BPM BPD, you must assign an undercover agent to it for the
message event to run at run time. The Event Manager, which is part of the IBM
Process Server, handles the scheduling and queuing of undercover agents. For
more information, see Undercover agents.
In addition to user-created complex business objects (variable types), the following
complex business objects can be used to invoke undercover agents at run time:
Table 1. Complex business objects that can be used to invoke undercover agents at
run time
Variable type
Record
Date and Time
Boolean

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 IBM BPM Structured types


All structured objects are passed as XML structures, where every object property
corresponds to an XML element.
For example:
Variable type: Customer - Name: String (John Doe) - Description: String (Single) Age: Integer (30)
is mapped to:
XML: <value> <Name>John Doe</Name> <Description>Single</Description> <Age>30</Age> </value>

Keep the following important rules in mind:


- Every object property is mapped to an XML Element with the same name as the
property name. The element name is case-sensitive. For example, if the property is
Name, the element name must be <Name>, not <name>.
- All XML element attributes are reserved. If you pass an attribute (excluding type),
an error is returned because the passed Document is not valid.
- When an array is passed, it is mapped as a sequence of XML elements with the
same name. There are two possibilities: Passing root level arrays: Every object
array item must be placed as content of an <item> element. For example:
<value> <item> <Name>John Doe</Name> <Description>Married</Description> <Age>30</Age> </item> <item> <Name>Jane
Doe</Name> <Description>Married</Description> <Age>31</Age> </item> </value>

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>

- If an object property is null , the corresponding element is skipped.

Passing Record type


The Record type is serialized in the same way as Structured types. However,
because all values are considered of type ANY, the type information must also be
passed (using the type attribute) in order for the correct objects to be instantiated
during de-serialization.

Passing Date/Time types


The format for passing dates is yyyy/MM/dd HH:mm:ss.S z .
Example:
- <value>2004/03/11 14:02:20.0 PST</value>
- <value>2000/02/20 11:10:20.0 GMT+6:00</value>
When the value is converted to the Calendar Java object, it preserves the time zone,
and no other modifications (such as adjusting it to the server time zone) is
performed.

Passing Boolean type


The valid values for the Boolean type are true or false(case is not considered).
Example:
<value>TRUE</value>

Passing Map type


A Map type is passed to an undercover agent using the following structure:
<value> <entry> <key> </key> <value> </value> </entry> </value> For example: <value> <entry> <key>TX</key>
<value>Texas</value> </entry> <entry> <key>CA</key> <value>California</value> </entry> </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.

Passing XMLDocument type


An XML Document is passed as an XML escaped string.
Example:
<value> <![CDATA[ <?xml version="1.0"?> <Customer> <Name>John Doe</Name> <Description>Married</Description> <Age>30</Age>
</Customer> ]]> </value>

Passing XMLElement type


An XML Element is passed as an XML escaped string.
Example:
<value> <![CDATA[ <Customer> <Name>John Doe</Name> <Description>Married</Description> <Age>30</Age> </Customer> ]]>
</value>

313

Passing XMLNodeList type


Every node is passed as an XML escaped string. The array of the nodes is encoded
as a sequence of <item> elements.
Example:
<value> <item> <![CDATA[ <Customer> <Name>John Doe</Name> <Description>Married</Description> <Age>30</Age> </Customer>
]]> </item>| <item> <![CDATA[ <Customer> <Name>Jane Doe</Name> <Description>Married</Description> <Age>31</Age>
</Customer> ]]> </item> </value>

Passing ANY type


When the type of an input parameter to an undercover agent is declared as ANY ,
the information about the actual type must be passed as part of the XML.
Example:
Define a process with one input parameter, Name , of type ANY . When the data is
encoded in XML, the actual type must be supplied as the value for the type
attribute. If the type is not passed, the String type is assumed.
<value type="String"> John Doe </value>

Parent topic:Creating inbound integrations

314

Publishing IBM Business Process Manager web services


IBM BPM can publish web services in the same way that it consumes web
services. Using a SOAP connection, external applications can call the IBM BPM
web service to initiate a particular service or set of services.

Before you begin


To perform this task, you must be in the IBM Process Designer desktop editor.

About this task


You can create and publish a web service to enable external applications to initiate
a particular IBM BPM service or set of services. Using a SOAP integration, external
applications can call the web service.
Note: See Building a sample inbound integration to learn how to build a sample
integration that includes a web service.
Follow these steps to create a web service that external applications can call:

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.

Parent topic:Creating inbound integrations

316

Web services compatibility


Web services conform to a flexible architecture that allows variation in web services
implementations. This variation unfortunately can lead to compatibility problems.
If you are experiencing problems when you call an external web service from a
business process, you should first check its compatibility with IBM Business
Process Manager. In the topic XML constructs not supported, these compatibility
problems are outlined and explained. Tables are provided that list errors and
warnings caused by incompatibilities. Once you know the source of the cause you
can correct the web service accordingly.
If you are using IBM Business Process Manager Advanced and experiencing web
services difficulties associated with incompatibilities, consider using an Advanced
Integration Service to give you access to Integration Designer. The web services
tools in Integration Designer have a variety of popular bindings and features that can
be used to handle most web services interactions.
You also have another alternative, particularly if you have IBM Business Process
Manager Standard, and that is to use a SOAP connector. In the following sections,
which show this approach, it is assumed that you have access to a service using
Web Services Description Language (WSDL) and that you can make a call to the
web service using the soapUI open source tool or another SOAP tool. These
instructions describe testing the web service with soapUI.
Note that IBM Business Process Manager Standard has the following restrictions:
- SOAP header: There is only support for a request SOAP header that passes
complex type parameters. There is no support for a SOAP header, either request
or response, that passes simple type parameters.
- SOAP / JMS: SOAP over JMS is not supported.
- SOAP faults are not supported.
- HTTP headers are not supported.
- The Remote Procedure Call (RPC) binding style is not supported.

- Verifying that the web service is working


First check that the web service is working. The web service must be working
before you can call it from a business process.
- Calling a web service using a SOAP connector
When you know the web service works, you should test it from within Process
Designer.
Parent topic:Integrating with web services, Java and databases

317

Verifying that the web service is working


First check that the web service is working. The web service must be working before
you can call it from a business process.

About this task


These steps let you determine if you have a proper, working URL containing the
expected WSDL file.
You can see the following steps with screen captures from a previous version in this
technote.

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

Calling a web service using a SOAP connector


When you know the web service works, you should test it from within Process
Designer.

Before you begin


To perform this task, you must be in the IBM Process Designer desktop editor.

About this task


These steps show you how to test your web service.
You can see the following steps with screen captures from a previous version in this
technote.

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;
}

Parent topic:Web services compatibility

320

321

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.
To see the integration from IBM Case Manager to IBM Business Process Manager,
read Copying IBM Case Manager solutions that are associated with IBM Business
Process Manager process applications.
You might also want to consider including cases in your process applications so that
they run directly on an IBM BPM process server. For more information, see Building
process applications.
- Adding an IBM Case Manager server
You require at least one IBM Case Manager server to build an IBM Case Manager
Integration service.
- Building the IBM Case Manager Integration service
Like other integration services, this service integrates with another system.
Specifically, this service integrates a business process developed in IBM Process
Designer with an IBM Case Manager case management solution.
- Building a query for a search case operation
A graphical interface helps you build a query to your IBM Case Manager solution.
- Processing a search case operation result
A search case operation result is often used with an update case operation. Since
an array is returned in a search case result, you would use JavaScript to iterate
through each element of the array and perform multiple updates.
- Data mapping in case operations
Each case operation requires that variables, or values in the case of input, be
mapped to the input and output fields. Using the auto-map function creates
variables, if required, and assigns variables of the right type to each field.
- Accessing an IBM Case Manager server using the Secure Sockets Layer
(SSL)
Some IBM Case Manager servers may use SSL for security protection.
Parent topic:Modeling processes

322

Adding an IBM Case Manager server


You require at least one IBM Case Manager server to build an IBM Case Manager
Integration service.

About this task


To add a server, follow these steps.

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

Building the IBM Case Manager Integration service


Like other integration services, this service integrates with another system.
Specifically, this service integrates a business process developed in IBM Process
Designer with an IBM Case Manager case management solution.

Before you begin


To perform this task, you must be in the IBM Process Designer desktop editor.
Note: The name for the IBM Case Manager solution you will use and the process
application that you are currently using to develop your IBM Case Manager
Integration service must be identical. Before developing your service, check that
your IBM Case Manager solution name and your process application name match.
Should you rename the IBM Case Manager solution in future you will also need to
rename the corresponding process application, and vice-versa.

About this task


To build an IBM Case Manager Integration service, follow these steps:

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

provides the case references.


- Update case: This operation lets you modify a case. See Processing a search
case operation result if you want to search for cases and then perform multiple
updates by iterating through the array object that is returned.
7. Beneath Case Type, select the type of case to use. For example, a case type
for a case pertaining to insurance claims might have an Auto Claim case type.
Should your case type change in the future you will need to repeat the previous
steps for the new case type name and regenerate the business objects which
you do in the next step. In other words, changing a case type name in an IBM
Case Manager solution is independent of creating this service.
8. Click Generate Types. This generation creates the business objects which are
used by variables to contain the data transferred between your service and the
case management server. To see the business objects, click Data.Note that
generating the business objects does not mean that you have created variables
with these business objects as types. You still need to create those variables to
handle the input and output data for each operation. In the next step on data
mapping, you can create these variables quickly by using an auto-map function.
9. Click Data Mapping. This section lets you create the map between the variables
for input and output. As stated previously, these variables need to be created. A
simple way to both create and map the input and output variables for an
operation is to use the auto-map function. The auto-map function creates private
variables for the business objects, which are used by the IBM Case Manager
Integration service. Click the auto-map icon to create these private variables.
The mapping structure for each operation is discussed in Data mapping in case
operations.
10. Save your work to update the process application with any changes to your
service.
Parent topic:Integrating BPDs with IBM Case Manager cases

326

Building a query for a search case operation


A graphical interface helps you build a query to your IBM Case Manager solution.

About this task


Follow these steps to add a query that can be used in a search case operation.

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

Processing a search case operation result


A search case operation result is often used with an update case operation. Since
an array is returned in a search case result, you would use JavaScript to iterate
through each element of the array and perform multiple updates.

About this task


Follow these steps to make multiple updates using a search case result.
Although this topic is about a search case, it could also be applied to a retrieve
case. For example, you could search for a case and for each case reference
returned perform a retrieve to get the properties of each case instance. You could
look upon this example as a pattern that can be used any time multiple case
references need to be processed.

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

already null so the decision node should continue */


tw.local.counter = -1;

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

Data mapping in case operations


Each case operation requires that variables, or values in the case of input, be
mapped to the input and output fields. Using the auto-map function creates
variables, if required, and assigns variables of the right type to each field.
This section shows you the mapping between the input and output fields.
- Input and output map for a create case operation
- Input and output map for a search case operation
- Input and output map for a retrieve case operation
- Input and output map for an update case operation

Input and output map for a create case operation


Input map:
- Case properties: An array of key-value pairs to initialize the properties of the
case. The types are generated by the Generate Types button when you build your
service. The properties have an integer, float, boolean, string or datetime type. The
cardinality (number of elements) of the properties is either a single element or
multiple elements.
Output map:
- Case reference: A reference to the IBM Case Manager case. It maps to the
CaseReference business object found in the System Data toolkit.
- Return code: A return code indicating if the operation was successful.
- Response message: A response message from the server.

Input and output map for a search case operation


Input map:
- CMIS query: A string of text containing the Content Management Interoperability
Services (CMIS) query.
Output map:
- Case references: An array of IBM Case Manager CaseReference objects that
match the query. They map to the CaseReference business object found in the
System Data toolkit.
- Return code: A return code indicating if the operation was successful.
- Response message: A response message from the server.

Input and output map for a retrieve case operation


Input map:
Case reference: A reference to an IBM Case Manager case. It maps to the
CaseReference business object found in the System Data toolkit.
Output map:
- Case instance: An instance of the case type. The types are generated by the
Generate Types button when you build your service.

330

- Return code: A return code indicating if the operation was successful.


- Response message: A response message from the server.

Input and output map for an update case operation


Input map:
- Case reference: A reference to an IBM Case Manager case. It maps to the
CaseReference business object found in the System Data toolkit.
- Case properties: An array of key-value pairs to initialize the properties of the
case. The types are generated by the Generate Types button when you build your
service. The properties have an integer, float, boolean, string or datetime type. The
cardinality (number of elements) of the properties is either a single element or
multiple elements.
Output map:
- Return code: A return code indicating if the operation was successful.
- Response message: A response message from the server.

Parent topic:Integrating BPDs with IBM Case Manager cases

331

Accessing an IBM Case Manager server using the


Secure Sockets Layer (SSL)
Some IBM Case Manager servers may use SSL for security protection.

About this task


These steps show you how to set up a connection to an IBM Case Manager server
using SSL.

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

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.
The user might have more of a management role, for example, monitoring the
progress of the process execution, or the user might be called upon as an expert to
collaborate with another user on an activity. It is important to keep each of these
roles, and their business goals, in mind when you are designing the different
features of your process.

- Configuring a role-based business user interface


Before you deploy your process application, you need to configure different
elements in the business process definition (BPD) to control the types of actions
that different business users can perform in the Process Portal, the types of data
they can search for and view, and the dashboards that they can access.
- Developing flexible and efficient process applications
After you have mapped out your process to include all of the normal task flows for
normal process execution, you can optimize your process to make it more flexible
and efficient for the business users who will be working with the application in the
Process Portal.
- Setting up collaboration features for business users
Business Process Manager provides several features that allow business users to
collaborate with other users while working with processes.
- Enabling process instance management for a BPD
In IBM Process Portal, process owners can use the Process Performance
dashboard to review the progress of processes and their instances. If the business
process is enabled and process owners are authorized, they can also act on
individual process instances in the Gantt chart to resolve issues, such as
bottlenecks.
- Generating names for process instances
When you run a BPD, IBM BPM creates a default name for the process instance.
This name is visible to business users in the Process Portal, allowing them to
distinguish between different instances of a process as they complete their work. In
Process Designer, you can change the way the process instance names are
generated for a BPD in the Process Portal.
Parent topic:Creating processes in IBM Process Designer

333

Configuring a role-based business user interface


Before you deploy your process application, you need to configure different
elements in the business process definition (BPD) to control the types of actions that
different business users can perform in the Process Portal, the types of data they
can search for and view, and the dashboards that they can access.
- Exposing business process definitions
Exposure settings for business process definitions (BPDs) enable you to establish
who can start the process and perform other tasks in the IBM Process Portal.
- Exposing heritage human services
In addition to implementing the activities in a business process definition (BPD),
the heritage human services that you create in IBM Process Designer can also be
used to customize the Process Admin Console or to create a custom dashboard
for IBM Process Portal. The exposure settings for a service depend on its intended
purpose.
- 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.
- Making business data available in searches and views
Before business users in IBM Process Portal can search for business data across
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:Designing process interactions for business users

334

Exposing business process definitions


Exposure settings for business process definitions (BPDs) enable you to establish
who can start the process and perform other tasks in the IBM Process Portal.

Before you begin


To perform this task, you must be in the IBM Process Designer desktop editor.

About this task


You need to expose a BPD to particular teams to establish who can:
- Start instances of the process in Process Portal
- View data for instances of the process in reports in Process Portal

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

Expose business data

Expose performance metrics

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

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.

Before you begin


To perform this task, you must be in the IBM Process Designer desktop editor.

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

Exposing heritage human services


In addition to implementing the activities in a business process definition (BPD), the
heritage human services that you create in IBM Process Designer can also be
used to customize the Process Admin Console or to create a custom dashboard for
IBM Process Portal. The exposure settings for a service depend on its intended
purpose.

Before you begin


To perform this task, you must be in the IBM Process Designer desktop editor.
For information about exposing client-side human services, see Exposing clientside human services.

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

- The name of the process application


- serviceName

- The name of the heritage human service


- snapshot

- The name of the snapshot


- com.lombardisoftware.errorPage

- The URL of the error page


- Input variables
- In the URL, input variables that are defined for the service have the following
format:&tw.local.variableName=value
The default configuration is defined in the 99Local.xml file. For more
information, see The 99Local.xml and 100Custom.xml configuration files. Also,
the following example shows how to customize the 100Custom.xml file to
enable the type-string-to-date configuration option:<common merge="mergeChildren">
<type-string-to-date merge="replace">true</type-string-to-date>
</common>

For heritage human services, variableName can be a system-defined


SimpleType or a BusinessObject that is based off a SimpleType variable (of
type String, Integer, Decimal, Date, Time, Selection). Date or Time are
allowed only after enabling the type-string-to-date configuration option.
Restriction: The type-string-to-date configuration option is applicable only
to heritage human services. It does not apply to client-side human services.
The default configuration is defined in the 99Local.xml file. For more
information, see The 99Local.xml and 100Custom.xml configuration files. Also,
the following example shows how to customize the 100Custom.xml file to
enable the type-string-to-date configuration option:<common merge="mergeChildren">
<type-string-to-date merge="replace">true</type-string-to-date>
</common>

- 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

Version of the heritage human service


The exposed service in the tip of the
default track is run.
The exposed service in the default
snapshot is run.
When you start a heritage human
service as a dashboard in Process
Portal, the version that is started is the
current working version of the heritage
human service if the version is
exposed. Otherwise, if there is an
active snapshot in which the heritage
human service is exposed, then the
snapshot version is started. If the
current working version is not exposed
and there are multiple active
snapshots in which the heritage human
service is exposed, then the latest
snapshot version is started.
You can export only one valid
snapshot when you generate a portlet
for a dashboard. When the portlet
communicates back to IBM Business
Process Manager, that snapshot must
be active.

Process Server
Process Portal

A portlet in an external portal server

- Enabling resumable services


To enable resumable dashboards for a process application, you must configure
the com.ibm.bpm.social.zResumable property.
- Globalizing dashboard names
If you want dashboard names in Process Portal to be available in multiple
languages, define a localization resource for each dashboard name.
- Generating portlets for heritage human services exposed as dashboards
If you exposed a heritage human service as a dashboard for a group of process
participants, and you want to use the dashboard in IBM WebSphere Portal,
generate a portlet. Then the portal server administrator can deploy the JSR 286
portlet to the portal server runtime environment.
Parent topic:Configuring a role-based business user interface
Related information:

341

Exposing client-side human services


Creating a team
Activating snapshots for use with IBM Process Portal
Generating portlets for heritage human services exposed as dashboards

342

Enabling resumable services


To enable resumable dashboards for a process application, you must configure the
com.ibm.bpm.social.zResumable property.

About this task


When an exposed heritage human service is invoked, the service instance and
associated data remains in the Process Portal user's session memory until one of
the following conditions occurs: the heritage human service ends, the Process Portal
user logs out, or the session times out due to inactivity.
If the Process Portal user navigates away from a heritage human service Coach, the
service instance remains in the user's session. Sessions are held in IBM Business
Process Manager server memory, which might result in large memory allocations if
many service instances accumulate. Therefore, consider the various service types
and the service lifecycle when authoring and exposing a heritage human service.
- Non-resumable services
- By default, services are not resumable. A new service instance is created each
time the service is invoked. If the service does not flow to an end node, each
instance remains in the Process Portal user's session (until logout or session
timeout), which can potentially utilize a large amount of server memory per
user. Therefore, services should typically flow to an end node so that the
service is removed from the Process Portal user's session immediately.
Startable services that are called from the Process PortalLaunch list and
administrative services that are called from the Process Admin Console are not
resumable.
- Resumable services
- Services can be called as resumable (called with zResumable=true). When a
service is resumable, a service instance is reused if a previously created
service instance is still available in the Process Portal users session. The
service state and any service variables set from the prior instance invocation
are still in session memory and are used. If the service does not flow to an end
node, one instance remains in the session and is available for reuse (until
logout or session timeout). If the dashboard service flows to an end node, the
service instance is removed from the session, and the next time the service is
resumed, the Process Portal user is prompted to restart the service. Resumable
services are often authored so that they do not end, which allows Process
Portal users to continue where they were when they logged out.
Dashboard Services called from Process Portal can be configured to be
resumable (called with zResumable=true).
Note: Only services invoked in a snapshot can be resumed. When invoking a
service in a tip, the service is never resumed, which supports iterative
development scenarios on Process Center.

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

- This parameter causes the user's dashboard session to be resumed. It is


appended by default to all dashboard URLs. The resumable instances are
stored per user session, so different users have different instances. When a
user logs out, all resumable instances are cleared. The parameter can be
used with the optional zClientHandle={key} parameter. If the process
application for the dashboard is added to the
com.ibm.bpm.social.zResumable list, dashboard services called from
Process Portal are automatically called with zResumable=true.
- zForceNew=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

Globalizing dashboard names


If you want dashboard names in Process Portal to be available in multiple
languages, define a localization resource for each dashboard name.

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

Generating portlets for heritage human services


exposed as dashboards
If you exposed a heritage human service as a dashboard for a group of process
participants, and you want to use the dashboard in IBM WebSphere Portal,
generate a portlet. Then the portal server administrator can deploy the JSR 286
portlet to the portal server runtime environment.

Before you begin


Make sure that the heritage human service is exposed to the appropriate group of
process participants who work with the dashboard at run time, and that the heritage
human service is exposed as a dashboard. Make sure that the heritage human
service has at least one snapshot and one coach.
The dashboard is available for the specified users in Process Portal by default. If
you complete the following procedure, the dashboard also is available for the
specified users as a portlet deployed on a WebSphere Portal server.
When you design heritage human services that you intend to expose as dashboards
that are deployed as portlets, consider the following guidelines:
- Work with the portal server administrator to understand how the dashboard portlets
are related to other portlets and services in the portal server runtime environment.
- Make sure that the IBM WebSphere Portal server is added to the trusted server list
as described in Adding servers to the trusted server list.
- Typically, heritage human services that are exposed as dashboards are not
services that end. However, you are not prohibited from using end events in the
heritage human services that you expose as dashboards. Remember that when a
dashboard portlet is deployed, and it contains an endpoint, the portlet ends, and it
must be restarted. If your coach is designed to end the service, the generated
dashboard portlet includes a Reload button for process participants to start a new
instance and refresh the dashboard.
- If a heritage human service contains two coaches with the same name, make sure
that all boundary events on the coaches have unique control IDs. If the boundary
event control IDs are not unique, process participants who use the dashboard
portlet might receive errors or unexpected portlet interactions.
- You can generate portlets for dashboards that contain heritage coaches, but you
cannot map heritage coaches to boundary events for dashboard portlets.
- If you use preprocessing and postprocessing for the heritage human service, pay
attention to where the processing occurs in relation to the boundary event.
Because portlets can be wired together and wired to other services, you might
need to move preprocessing and postprocessing so that the boundary event
triggers properly in the dashboard portlet.
- If you are planning to update variables within a coach from an inbound event, but
you do not want trigger any of the boundary events for the coach, add a new
boundary event that loops back to the same coach that is specified as part of an
inbound event. Make sure to select the new boundary event when you define the
inbound event for the generated dashboard portlet.
- If you are planning to designate a payload variable for inbound or outbound events
for the dashboard, make sure that the payload variable is included on each coach

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.

About this task


Use the Export Dashboard wizard in Process Designer to define portlet parameters
and map events when exporting the dashboard. After you generate a portlet for the
dashboard, your portal server administrator can deploy the portlet to IBM
WebSphere Portal so that the process participants interact with the dashboard in the
runtime environment.

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

page in Process Designer to open the Export Dashboard wizard.


2. When setting the parameters for the portlet, consider how the portal server
administrator and the process participants use the deployed portlet:
- Enter a name and a description that describe what the portlet does.
- If you created an XML file for globalization of the name and description of the
portlet, select Globalization and browse to the file.
- Select the snapshot that represents the version of the dashboard that you want
to be generated as a portlet for process participants to use at run time. If you
select an older snapshot, changes after the snapshot was taken are not
represented in the generated portlet.
3. Optional: Define inbound events for the dashboard portlet.At run time, other
portlets interact with the dashboard portlet by sending events to it. When the
dashboard portlet receives an event from another portlet, it fires a boundary
event, moving the dashboard to another coach.
- For each inbound event that you want this dashboard portlet to respond to,
change the event name field to something meaningful to your dashboard. The
namespace default value makes the event unique and prevents unintended
interactions between portlets.
- Specify a payload variable if you expect the inbound event to contain data that
you want to use to update the dashboard data. If the coach uses a payload
variable, select the payload variable that the dashboard portlet receives from
other portlets at run time. You can choose from variables that are part of the
heritage human service. As previously mentioned, ensure that the payload
variable is included on each coach that is part of the heritage human service.
- Select a coach and a boundary event that represents the user interface element
that you want the dashboard portlet to interact with when it receives the event.
The boundary event in a heritage human service diagram is labeled as End
State Binding. If you selected a payload variable, make sure to select a coach
that has the same variable.
- Define multiple interface elements by clicking the plus sign and designating
another coach and boundary event.
- When the dashboard portlet receives the event, it interacts with only the
interface element on the currently displayed coach.
4. Optional: Define outbound events for the dashboard portlet.At run time, the
dashboard portlet sends events to other portlets.
- Select a boundary event to designate user interface elements that cause the
dashboard portlet to send the event.
- If you specify a payload variable, the dashboard portlet includes data in the sent
event for other portlets to use. As previously mentioned, ensure that the payload
variable is included on each coach that is part of the heritage human service.
5. After you finish exporting the dashboard as a portlet, install the .war file on your
IBM BPM server and tell the portal server administrator to point to the endpoint for
the Web Services for Remote Portlets (WSRP) 2.0 protocol and import the .war
file. The IBM BPM server comes with a WSRP 2.0 provider already installed,
which allows consumption of portlets generated from WebSphere Portal. The
URL for accessing the WSPR 2.0 provider web service on an installed IBM BPM
server is: http://{BPM_host_name}:{BPM_port
}/producer/wsdl/wsrp_service.wsdl. For information on using WebSphere
349

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

- If using personal certificates for testing or in a pre-production environment, the


administrator can import the certificates from each system into the browser
before testing.
- In a production environment, administrators should avoid using self-signed
certificates.
- If using HTTPS to connect to WebSphere Portal, the administrator should also
use HTTPS in the dashboard portlets. If a part of a page is loaded using
HTTPS, and other parts are loaded using HTTP, process participants who
connect to WebSphere Portal and use the dashboard portlets might receive a
warning that some content on the page is not secure.
- The portal server administrator should determine whether to use client-side
events or server-side events. Both client-side events and server-side events use
the boundary events that are modeled as part of the heritage human service
definition. The difference between client-side events and server-side events is
the channel for communication.When using client-side events, the portlets
created with Process Designer use the Dojo Toolkit to send messages between
portlets that are on the same page in the portal server. Using client-side events
is faster, because it does not require events to be sent to the server for
processing and does not require page reloads when an event is sent or
received. If client-side events are used, the Dojo Toolkit must be loaded as part
of the theme for the portal page, and the generated dashboard portlets send
events using only the Dojo Toolkit. The generated dashboard portlets receive
server-side events from other portlets on the page that are not using client-side
events.
Server-side events do not require the Dojo Toolkit to be loaded and are the
standard event mechanism defined in the JSR286 specification. Server-side
events take longer to process because the events must be sent to the server for
processing and the page must be reloaded to display the results. Server-side
events can be used across portal server pages with the correct portal
configuration and wiring.
- If the administrator decides to use client-side events, the Dojo Toolkit must be
loaded as part of the theme for the portal page. See the WebSphere Portal V8
documentation Changing the theme default profile or the WebSphere Portal
V7.0.0.2 documentation, which requires two steps: Installing a new theme and
enabling the full profile to use Dojo by default as described in Theme
enablement.

Parent topic:Exposing heritage human services


Related information:
Exposing heritage human services

351

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.

Before you begin


To perform this task, you must be in the IBM Process Designer desktop editor.

About this task


The exposure settings for a service depend on its intended purpose. Note: For
information about exposing heritage human services, see Exposing heritage human
services.

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

Do Not Expose (Instance details UI


for a BPD or case type)

Use this option to indicate that the


client-side human service cannot be
exposed because it implements an
instance details user interface that is
used for a process instance or case
instance. When you create the BPD or
case type and create the details user
interface under Details UI in the Views
folder, you also create the client-side
human service that implements the user
interface for the specified process or
case instance.
When this option is displayed for a
client-side human service, the Expose
as and Expose to start settings in the
Overview folder are disabled. The
exposure of this client-side human
service is determined only by the
settings in the Views folder of the
corresponding BPD or case type.

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

Default version of the client-side human


service
The version of the exposed service that
runs is the one that is in the current
working version of the default track.
The version of the exposed service that
runs is the one that is in the default
snapshot.
When you start a client-side human
service as a dashboard in Process
Portal, the version that is started is the
current working version of the client-side
human service if the version is exposed.
Otherwise, if there is an active snapshot
in which the client-side human service is
exposed, the snapshot version is started.
If the current working version is not
exposed and there are multiple active
snapshots in which the client-side human
service is exposed, the latest snapshot
version is started.

Parent topic:Configuring a role-based business user interface


Parent topic:Modeling client-side human services

355

Making business data available in searches and


views
Before business users in IBM Process Portal can search for business data across
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.

Before you begin


To perform this task, you must be in the IBM Process Designer desktop editor.

About this task


As you model the business data for your process application, consider what type of
data a business user might want to search on while working with the process. You
also should consider which business data provides necessary information about a
task to help users complete the task from the task view if it is an in-line task, or
which provides a quick way for users to understand something about that task
instance without opening the coach for the task. These are the variables that you
need to configure in the Process Designer to be searchable and viewable in the
IBM Process Portal.

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

Developing flexible and efficient process


applications
After you have mapped out your process to include all of the normal task flows for
normal process execution, you can optimize your process to make it more flexible
and efficient for the business users who will be working with the application in the
Process Portal.

About this task


At design time, there are several things that you can do to save the business user's
time and make it easier for them to complete their work:

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

threads that are shared between activities.


- Automatically starting the user's next task
To help your business users be maximally efficient while they are using your
application, consider places in your process where you expect the same user to be
completing multiple tasks in sequence.
- Defining ad hoc actions (deprecated)
While a process is running, a user might need to launch a new activity or set of
activities, such as updating a customer's contact information or canceling the
process instance. The process designer can define a set of these unplanned, or
ad hoc, actions to be launched by the user from action menus in the Process
Portal.
Parent topic:Designing process interactions for business users

359

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.

Before you begin


To perform this task, you must be in the IBM Process Designer desktop editor.

About this task


There are three types of tasks that can be configured to be completed by the user
from within their task list without requiring the user to open the coach interface: a
simple approval or rejection, a simple completion, or a simple choice between a set
of options.Table 1. Inline completion task type characteristics
Task Type
Simple
Approval

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

Use when the


task requires
the business
user to indicate
task completion
based on the
task narrative
and the task
details that are
exposed in the
task list. For
example, in a
simple
completion task
the user might
only need to
indicate that
they have
reviewed the
task narrative
and the
exposed task
details, and
include a
comment.
Use when the
task requires
the business
user to choose
between a list
of options.

None.

comment Type:
String

choices Type: decision Type:


String, List. Stringcomment
By default these Type: String

choices are
tw.resource.S
impleChoice.A
pprove,
tw.resource.S
impleChoice.R
eject

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.

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

For each option that is presented to the user, add an autoObject[n]


parameter and a string value. For example, if you are creating inline
completion buttons for computer configuration, you might have the following:
var autoObject = new tw.object.arrayOf.String();
autoObject[0] = "Single Core";
autoObject[1] = "Dual Core";
autoObject[2] = "Quad Core";
autoObject

F. Save the BPD.


7. In the Data Mapping tab, the inputs and outputs required by the predefined
service are already added. Map the relevant variables that are specific to your
process to the data required by the predefined service. For example, if you
created a simple choice task drawing from a list of options defined in a private
variable, then you must map this variable to the choices(List of String)
variable associated with the Simple Choice service.
Parent topic:Developing flexible and efficient process applications
Related information:
Mapping input and output data for an activity or step

362

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 threads that are
shared between activities. By default, new BPDs are not optimized for latency,
which means that, between activities, instances return their execution threads to the
shared thread pool. You can change the optimizing setting for a BPD in Process
Designer.

About this task


The execution of implementations of system tasks and decision tasks, is scheduled
by the Event Manager. Every cluster member has one Event Manager, which uses a
pool of threads to schedule work in the order that it was created. This use of a pool
of threads makes it possible for implementations of a BPD to run independently and
in parallel.
If the IBM BPM system is running under high load, the processing of an
implementation of a specific process instance might be delayed because other work
is already scheduled to be executed before it. This thread sharing behavior can
increase the latency for the overall process instance. However, some types of BPD
need higher performance to minimize the straight-through processing latency. If a
straight-through processing BPD does not contain any parallel paths, but performs a
series of system tasks or decision tasks that are implemented by integration
services, this work might be run more efficient and with less latency by using a
single thread on one cluster member.
This optimization setting defines two classes of BPD:
- The default processing behavior is not optimized for latency, which means that the
thread is released after each unit of work. This behavior ensures that all BPD
instances that use the default setting have an equal chance to continue navigation
of the process.
- BPD system tasks and decision tasks that are optimized for latency are executed
on the same thread that the BPD uses for navigation. If multiple system tasks or
decision tasks exist in parallel paths of the BPD, only one path is executed by the
same thread, the other paths are scheduled to use the default behavior by the
Event Manager. Process instances with this execution optimization use the Event
Manager threads for longer and so they provide a more predictable latency.
You must take care to avoid causing a negative performance impact on other
instances, services, undercover agents, and other functions that use the shared pool
of threads.
- Do not enable this optimization option for all BPDs in your system, otherwise the
wait time to acquire one execution thread might increase for your process
instances.
- Make sure that the number of requests for BPDs that have this optimization
enabled that are sent to a cluster member per unit of time does not exceed the
capacity of the execution threads that are available to process the requests.

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

Automatically starting the user's next task


To help your business users be maximally efficient while they are using your
application, consider places in your process where you expect the same user to be
completing multiple tasks in sequence.

Before you begin


To perform this task, you must be in the IBM Process Designer desktop editor.

About this task


Normally, for each task that users are assigned, they must start the task from their
task list, complete the work for that task, then return to the task list for the next
activity. You can save users from having to go back to the task list when the next
task in the process is also assigned to them. For example, a customer service agent
might be assigned a task for opening a new customer account that is followed
immediately by a task for taking the new customer's order. Instead of having the
user return to his or her task list to retrieve the second task after the first one
completes, you can designate that the coach for the second task opens immediately
upon completion of the first task.

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

Parent topic:Developing flexible and efficient process applications


Related information:
The 99Local.xml and 100Custom.xml configuration files

366

Defining ad hoc actions (deprecated)


While a process is running, a user might need to launch a new activity or set of
activities, such as updating a customer's contact information or canceling the
process instance. The process designer can define a set of these unplanned, or ad
hoc, actions to be launched by the user from action menus in the Process Portal.
Important: Ad hoc actions are deprecated in version 8.5.5.0, instead use Creating
an unstructured (ad hoc) activity.

Before you begin


To perform this task, you must be in the IBM Process Designer desktop editor.
To use ad-hoc tasks, Process Portal users must be members of a security group
that is configured for the ACTION_INJECT_TOKEN policy. For information about
security groups, see Setting up users, groups, and teams. For information about the
ACTION_INJECT_TOKEN configuration, see Configuring access to Process Portal
action policies. For information about managing the security groups, see Creating
and managing groups.
Restriction: Ad hoc start events are not supported in simple loop or multi-instance
loop activities. The activity that calls the business process definition (BPD) should
not be configured for looping.

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

Setting up collaboration features for business users


Business Process Manager provides several features that allow business users to
collaborate with other users while working with processes.

About this task


Within the Process Portal environment, users can request help from other users,
collaborate in real time with other users on task completion, and communicate
through messages in the process activity stream. All of these features are available
without any configuration of your process applications. However, you can also
enable users to chat with one another using Lotus Sametime Connect. You can also
specify a set of expert users for a given activity so that users can immediately
identify the best person to ask for assistance in completing a task.
- Enabling Sametime Connect integration for Process Portal
You can enable instant messaging support to allow your end users to
communicate in real time with others in the organization as they work on process
activities.
- Specifying experts for an activity
Business users working with your process applications can collaborate or request
assistance from expert users associated with a given task or activity. The list of
experts appears in the Experts panel in the Process Portal environment.
- Enabling IBM Connections integration for Process Portal
If your environment is configured for IBM Connections, you can set up Process
Portal so that business card information displays when users click an avatar or a
name. With IBM Connections V4.0 or later, you also can enable users to, after they
set preferences, receive notifications in IBM Connections when new tasks are
assigned to them.

Parent topic:Designing process interactions for business users

369

Enabling Sametime Connect integration for Process


Portal
You can enable instant messaging support to allow your end users to communicate
in real time with others in the organization as they work on process activities.

Before you begin


To perform this task, you must be in the IBM Process Designer desktop editor.
Ensure that your administrator has configured your Process Portal environment for
IBM Lotus Sametime Connect integration. You will need the Sametime Connect
server location information in order to complete this task.To make changes to the
Process Portal environment, you must be logged into Process Designer with a user
ID with administrative rights.

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

- The name of your Sametime Connect server.


- secureport

- The port for the Sametime Connect server.


If your setup is configured correctly, you will see the Lotus Sametime login
window.
7. Create a snapshot of the application, and install the snapshot on Process Server.

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

Specifying experts for an activity


Business users working with your process applications can collaborate or request
assistance from expert users associated with a given task or activity. The list of
experts appears in the Experts panel in the Process Portal environment.

Before you begin


To perform this task, you must be in the IBM Process Designer desktop editor.
An activity must be associated with a human service before it can be assigned
experts.

About this task


Each activity in Process Portal can list two types of experts:
- Users who have completed this activity in the past, based on historical analysis.
This list is limited to a small group of users who have completed the activity most
frequently.
- Users belonging to a team that is explicitly specified in Process Designer as an
expert group for this activity.

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

Enabling IBM Connections integration for Process


Portal
If your environment is configured for IBM Connections, you can set up Process
Portal so that business card information displays when users click an avatar or a
name. With IBM Connections V4.0 or later, you also can enable users to, after they
set preferences, receive notifications in IBM Connections when new tasks are
assigned to them.

Before you begin


Ensure that IBM Connections is configured for your environment. You need the IBM
Connections server location information to complete this task.If you want users to
see the IBM Connections avatar instead of the IBM BPM avatar, the proxyconfig.xml file must contain a proxy policy for the URL of the IBM Connections
server. For information about updating the proxy configuration, see Configuring the
Business Space Ajax proxy and Adding proxy policies to the Business Space Ajax
proxy.
If you want users to receive activity notifications, and you have IBM Connections V4
or later, ensure that your administrator configured the IBM Connections integration.
See Configuring IBM Connections integration for task notifications.
Restriction: When coach views are displayed in IBM Connections, the width is
limited to 380 pixels. To modify the width of a coach view using the media type, see
Defining coach view behavior.
To change the Process Portal application, log in to IBM Process Designer with a
user ID with administrative rights.

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

for IBM Connections.


6. Click Test Connection. This tests if the user ID and password successfully
connect to the IBM Connections server. Tip: The test does not include SSL
certification. On the administrative consoles for your production systems, verify
that the administrator exchanged SSL certificates between the IBM Connections
server and IBM Business Process Manager as described in Configuring IBM
Connections integration for task notifications.
If your setup is configured correctly, a message appears.
7. Create a snapshot of the application, and install the snapshot on Process Server.

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.

Parent topic:Setting up collaboration features for business users

373

Enabling process instance management for a BPD


In IBM Process Portal, process owners can use the Process Performance
dashboard to review the progress of processes and their instances. If the business
process is enabled and process owners are authorized, they can also act on
individual process instances in the Gantt chart to resolve issues, such as
bottlenecks.

Before you begin


To perform this task, you must be in the IBM Process Designer desktop editor.

About this task


If the business process is enabled for process instance management, process
owners can use the Process Performance dashboard and the Gantt chart to
complete the following tasks:
- View and change the projected path for a running instance.
- Determine whether a running process instance is on track for completion.
- Change the due date of a running process instance.
- Adjust the due dates and durations of tasks in a process instance.

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

5. Enable projected path management.Projected path management is enabled for


processes by default in the Advanced section on the Overview tab. There are
several routes, or paths, that can be followed to complete a process. With
projected path management enabled, the projected path for an instance can be
displayed on the Gantt chart if distinct paths from the start to end nodes are
found.
If projected path management is not enabled, the Process Performance
dashboard and the Gantt chart are affected in the following ways:
- Process Performance dashboard: No estimated completion time for entries in
the Instances in progress list:
- Gantt chart Set Path page: No projected path.
- Gantt chart Gantt View page:
- No future tasks
- No estimated completion time
- Task durations are not editable
6. Optional: Enable the collection of historical data in the Performance Data
Warehouse.Historical data is used in the Set Path page of the Gantt chart to
display the traversed path and calculate the projected path for a running process
instance.
A. On the Overview tab, ensure that Enable tracking field is selected.
B. On the Tracking tab, ensure that Enable Autotracking is selected.
C. Send the updated tracking definitions to the Business Performance Data
Warehouse.
If autotracking is not enabled, the Gantt chart is affected in the following ways:
- Historical path information is not available for the instance.
- The projected path through the instance is based on the longest (pessimistic)
path and not the typical historical path.
7. Optional: Enable process owners to analyze the average amount of time that
elapses between steps in the process.To enable time lapses to be analyzed,
include tracking points in the process and create a timing interval to capture the
time between the defined points. If tracking points are defined for the process,
timing intervals are sent to the Performance Data Warehouse and the Process
Performance dashboard includes timing intervals on the Overview page.

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

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.

About this task


The default work schedule for all BPDs is specified in the 99Local.xml
configuration file in the following directory, where server_type is either processserver or process-center: PROFILE_HOME\config\cells\cell_name\nodes\
node_name\servers\server_name\server_type\config\system. If you do not
specify a work schedule for a BPD, or if you leave the settings at use default, date
calculations for instances of the BPD are based on the <default-work-schedule>
in the configuration file.

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.

Parent topic:Setting the work schedule for a BPD

379

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.

About this task


Avoid removing the default holiday or time schedules. The default schedules are
specified in the 99Local.xml configuration file. Changes to the default schedules
require changes to the 99Local.xml file.

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

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.

About this task


In IBM Process Portal, tasks are listed according to their due date status. Activity
due dates and the projected path are also used to calculate the expected completion
time for a process instance.
By default, the due date of a human task is 1 hour from the time of task creation.
You can modify this duration for each activity in your process. Administrators can
also change the default duration after deployment. If projected path management is
enabled for the process, authorized business users can change the due date for
individual tasks and the overall process instance in Process Portal.
The calculation of the activity due date is also affected by the working hours that
users are available to complete work. The working hours depend on the values that
you specify for the time schedule, time zone, and holiday schedule.

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

parameters for the TWHolidaySchedule variable, go to the System Data toolkit


and open the variable.

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.

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

382

Generating names for process instances


When you run a BPD, IBM BPM creates a default name for the process instance.
This name is visible to business users in the Process Portal, allowing them to
distinguish between different instances of a process as they complete their work. In
Process Designer, you can change the way the process instance names are
generated for a BPD in the Process Portal.

Before you begin


To perform this task, you must be in the IBM Process Designer desktop editor.

About this task


By default, the name for each instance of a process is the BPD name plus the
instance ID. The name for a given process instance is displayed in many different
places in the Process Portal, including the users Work list, in the dashboards and in
the details for all the tasks associated with the process instance. To modify the way
that the process instance names for a given BPD are generated, complete the
following steps.

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

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.
- Tracking IBM Business Process Manager performance data
To create customized and third-party reports in IBM BPM, you identify the data to
track and send that data to the Performance Data Warehouse.
- Sending tracking definitions to Performance Data Warehouse
In order to track performance data, you need to send tracking definitions to the
Performance Data Warehouse. Each time you update your tracking requirements
in IBM Process Designer, you must send the updated definitions to Performance
Data Warehouse.
- Exposing performance scoreboards
The performance scoreboards are not exposed by default. If you want to expose
them to your Process Portal users, you must complete some manual steps.
- Defining reports in Process Designer (deprecated)
Reports enable you to analyze business data that is specific to your processes.
You can specify the variables to track and define the report to query your tracked
data. Users can view the resulting report scoreboards from the Dashboards page
in Process Portal. Instead of using the deprecated reporting capabilities, consider
using dashboards that you design in Coaches.

Parent topic:Creating processes in IBM Process Designer


Related information:
Using IBM Business Monitor with process applications

384

Tracking IBM Business Process Manager performance data


To create customized and third-party reports in IBM BPM, you identify the data to
track and send that data to the Performance Data Warehouse.
To track data in a business process definition (BPD), use autotracking, tracking
groups, or both.
- Autotracking automatically captures data from tracking points at the entry and exit
of each item in a BPD (for example, services, activities, and gateways). To enable
autotracking, make sure that Enable Autotracking is selected under the Tracking
tab of the BPD. (By default, the checkbox is not selected, which is better for
performance.) Your system administrator can change this default.
- Tracking groups provide more control over tracked data. For example, use tracking
groups track a selected group of process variables across multiple BPDs or
process applications and to store tracking points for a timing interval. To enable
tracking groups, make sure that Enable Tracking is selected under the Overview
tab of the BPD. (By default, the checkbox is selected.) Your system administrator
can change this default. Note that the Enable Tracking setting does not apply to
services with tracking points. Tracking data is always enabled when services
contain tracking points.
You can use both tracking methods in one BPD. If you use both autotracking and
tracking groups, you can create a timing interval.
After you configure data tracking for your BPD, and each time after that
configuration that you update your data-tracking requirements, you must send the
tracking definitions to the Performance Data Warehouse. When you send tracking
definitions, either directly or as part of deploying a snapshot, the Performance Data
Warehouse establishes the structure in its database to hold the data that Process
Server generates 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 that
Process Server generates.
When you change your tracking requirements in Process Designer, you must send
the definitions to the Performance Data Warehouse. Therefore, you are developing
process applications on Process Center Server, be sure to send definitions after you
change each process application. For process applications that are deployed in
runtime environments, create a snapshot of your changes and deploy the new
snapshot to ensure that the data you want to collect is available in the runtime
environment.
- Data tracking considerations
Before you implement data tracking in a process application, make sure you
understand the supported data types and naming conventions, as well as any
considerations for working with versioned data.
- Autotracking IBM Business Process Manager performance data
Use autotracking if you want to capture data to quickly configure and publish
reports using the ad hoc wizard, or if you want to capture data that automatically
includes tracking points at the entry and exit of each item in a BPD. For example,
use autotracking if you know that you want to compare the duration for each

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

Data tracking considerations


Before you implement data tracking in a process application, make sure you
understand the supported data types and naming conventions, as well as any
considerations for working with versioned data.

Supported data types


Data types that IBM BPM tracks include the following:
Type of tracking
Autotracking
Tracking groups

Supported data types


String, Integer, Decimal, Boolean, and
Date
String, Number, and Date

When you are tracking data, be aware of the following:


- A tracking group can have a maximum of 50 fields for each of the data types. Do
not increase the maximum number of fields because it can affect the database
table size and future migration to a new IBM BPM release.
- Variables for which the Is List option is enabled cannot be tracked.
- Complex types cannot be mapped directly; their fields must be mapped
individually.
- Variables of type ANY, Map, Record, XMLDocument, XMLElement, and
XMLNodeList cannot be tracked.

Naming tracking groups


When naming tracking groups and tracked fields, be aware of the following
restrictions:
- Do not use SQL-92 reserved words. Several sources available on the internet
provide a complete list of SQL-92 reserved words.
- Do not use any of the names used for the views and fields in the Business
Performance Data Warehouse database schema.

Tracking data across processes and process applications


To track data from multiple processes (BPDs) that reside in the same process
application, create a tracking group and implement it for as many BPDs as you like,
mapping the tracked fields to the appropriate variables for each BPD.
If you want to capture data from multiple processes (BPDs) that reside in different
process applications, you can do so by using the same tracking group in each
process application. For example, you can create a tracking group in a toolkit, and
then create a dependency on that toolkit in each process application where you
want to use the tracking group. From each process application, you can implement
the tracking group one or more times, mapping the tracked fields to variables within
each application. When you send tracking definitions and then run instances of the
BPDs, the data is captured in a single tracking group view as described in "Business
Performance Data Warehouse tracking group views." The data that IBM BPM
captures enables you to analyze the tracked data in any way you choose. For
example, you can analyze the tracked fields as a whole or you can compare the
data from each process application or from each process.
387

Working with versioned data


All data tracked by IBM BPM includes snapshot (version) information that enables
you to create reports to compare versions of your processes if you have that
requirement.
When tracking data, keep the following in mind:
- Timing intervals work across snapshots (versions). For example, a process that
starts in one version (1.0) might be migrated to a new version (2.0) before reaching
the end of a timing interval. In such a case, the data for the timing interval is
captured in the Performance Data Warehouse as expected with the version
change noted.
- Data types of variables that are being stored (autotracked or part of a tracking
group) can change between versions. If data types do change, a new column is
created in the corresponding view as described in "Performance Data Warehouse
database architecture."

Parent topic:Tracking IBM Business Process Manager performance data


Related information:
Business Performance Data Warehouse tracking group views

388

Autotracking IBM Business Process Manager performance


data
Use autotracking if you want to capture data to quickly configure and publish reports
using the ad hoc wizard, or if you want to capture data that automatically includes
tracking points at the entry and exit of each item in a BPD. For example, use
autotracking if you know that you want to compare the duration for each activity in a
BPD.
When you enable autotracking for a BPD, you also track the following Key
Performance Indicators (KPIs) associated with your BPD.
- Custom KPIs associated with your BPD
- Custom KPIs associated with the activities in your BPD
- The Total Time KPI associated with each BPD by default
KPIs act as conditions for Service Level Agreements (SLAs), which you can use to
trigger a particular consequence such as an email notification. You can analyze the
performance of your SLAs using the SLA Overview dashboard that is available in
Process Portal. To create custom SLA reports, use the SLASTATUS view and the
SLATHRESHOLDTRAVERSALS view in the Business Performance Data
Warehouse database.
Autotracking is not required for the Process Performance and Team Performance
dashboards, but some features of the Process Performance dashboard are not
available without autotracking. For more information, see Enabling process instance
management for a BPD.
- Key performance indicators (KPIs) and service level agreements (SLAs)
With the data that IBM Business Process Manager tracks and stores for key
performance indicators (KPIs), you can analyze process performance and create
service level agreements (SLAs).
- Creating custom KPIs
You can use key performance indicators (KPIs) to analyze process performance
and create service level agreements. IBM Business Process Manager tracks KPI
measurements at process run time and stores the information in the Business Data
Warehouse.
- Associating KPIs with activities
To use a KPI in IBM Business Process Manager, you must associate it with one or
several activities.
- Creating SLAs
Create service level agreements (SLAs) so that you can analyze the performance
of your business processes over time.
- 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.
Parent topic:Tracking IBM Business Process Manager performance data

389

390

Key performance indicators (KPIs) and service level


agreements (SLAs)
With the data that IBM Business Process Manager tracks and stores for key
performance indicators (KPIs), you can analyze process performance and create
service level agreements (SLAs).

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

Custom SLA reports (deprecated)

Historical analysis in the Optimizer view

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.

Parent topic:Autotracking IBM Business Process Manager performance data


Related concepts:
Business Monitor KPIs

392

Creating custom KPIs


You can use key performance indicators (KPIs) to analyze process performance and
create service level agreements. IBM Business Process Manager tracks KPI
measurements at process run time and stores the information in the Business Data
Warehouse.

Before you begin


To perform this task, you must be in the IBM Process Designer desktop editor.

About this task


To create a custom KPI for IBM Business Process Manager, complete the following
procedure.

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

Associating KPIs with activities


To use a KPI in IBM Business Process Manager, you must associate it with one or
several activities.

Before you begin


To perform this task, you must be in the IBM Process Designer desktop editor.

About this task


Follow these steps to alter associated KPIs or associate a new KPI with an activity
in a business process definition (BPD):

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.

Value per Hour (calendar)


Absolute Value
Custom JavaScript
True after N traversals (for Rework
KPI only)

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

expect by providing minimum, expected, and maximum values in the appropriate


fields. IBM BPM uses the specified thresholds as the range for producing heat
maps and recommendations in the Optimizer. You can also use KPIs to specify
conditions that trigger service level agreements (SLAs).
7. Click the Save icon in the toolbar to save your changes.
Parent topic:Autotracking IBM Business Process Manager performance data

395

Creating SLAs
Create service level agreements (SLAs) so that you can analyze the performance of
your business processes over time.

Before you begin


To perform this task, you must be in the IBM Process Designer desktop editor.

About this task


When you run instances of your processes, SLA consequences do not trigger until
the associated activity starts or completes. With SLAs you can report violations and,
over time, understand the trend in violations. Use other methods, such as timer
events, to enable Process Portal users to immediately react to time-based
conditions.
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 the following
procedure.

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.

Before you begin


To perform this task, you must be in the IBM Process Designer desktop editor.

About this task


To use autotracking, perform the following steps.

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

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.

About this task


Tracking groups provide the following advantages:
- You can group similar data together for analysis. For example, you can track
employee data, account data, or shipment status information in independent
tracking groups.
- You can track process variables across multiple BPDs and process applications.
For example, if your organization includes several locations and each location has
a similar, but unique, onboarding process for new employees, you can create a
tracking group to capture the business data for all of these processes.
- Tracking points for a timing interval can span multiple BPDs. For example, if you
want to measure the duration between steps that start in one process and end in a
nested process, you can include the start tracking point in the main process and
the end tracking point in the nested process.

- Creating a tracking group


Create and use a tracking group to track process variables across multiple
business process definitions and process applications, or to store tracking points
for a timing interval. Use tracking groups when you want to explicitly control your
tracked data and tracking points for more advanced custom reports.
- Associating process variables to a tracking group
You can associate process variables to a tracking group in order to track them.

Parent topic:Tracking IBM Business Process Manager performance data

399

Creating a tracking group


Create and use a tracking group to track process variables across multiple business
process definitions and process applications, or to store tracking points for a timing
interval. Use tracking groups when you want to explicitly control your tracked data
and tracking points for more advanced custom reports.

Before you begin


To perform this task, you must be in the IBM Process Designer desktop editor.

About this task


Use the Process Designer to create a tracking group, assign tracking events to it,
and send the tracking information to the Business Performance Data Warehouse.

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.

Parent topic:Tracking groups of process variables

400

Associating process variables to a tracking group


You can associate process variables to a tracking group in order to track them.

Before you begin


You must create a tracking group to hold the process variable data that you want to
track.To perform this task, you must be in the IBM Process Designer desktop
editor.

About this task


After you create a tracking group, use the following steps to associate process
variables with each tracked field in the tracking group.

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

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.

Before you begin


Do the following tasks before creating a timing interval:
- Open the IBM Process Designer desktop editor.
- Enable autotracking
- Add tracking points to the BPD
- Create a tracking group to hold the timing interval data. Ensure that you add each
tracking point to the tracking group that you create.

About this task


When you create a timing interval for the process, process owners can use the
Process Performance dashboard in Process Portal to calculate the duration of a
process, or compare the duration of several processes.

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

Sending tracking definitions to Performance Data


Warehouse
In order to track performance data, you need to send tracking definitions to the
Performance Data Warehouse. Each time you update your tracking requirements in
IBM Process Designer, you must send the updated definitions to Performance
Data Warehouse.

About this task


When developing on the Process Center Server, be sure to send definitions when
you make changes. For process applications deployed in runtime environments,
snapshot any changes and deploy the new snapshot to ensure that the data you
want to collect is available in the runtime environment.
The method of sending tracking definitions varies depending on the type of server
you are using.
Server

Description

Process Center Server

When you use


autotracking, manually
create or edit tracking
groups, or perform any
other task in the Designer
in IBM Process Designer to
capture performance data,
you must send these
tracking requirements to
the Performance Data
Warehouse if you plan to
run your processes on the
Process Center Server to
test data tracking and
reports.
If IBM Business Monitor is
installed, its tracking
definitions (part of a
monitor model) are
updated when you use this
menu item.

404

How to send tracking


definitions
In Process Designer, click
File > Update Tracking
Definitions.

Process servers in runtime When you deploy


environments
snapshots of process
applications on process
servers in runtime
environments, all tracking
definitions are
automatically sent to the
Performance Data
Warehouse in the selected
runtime environment. This
ensures that your data is
tracked as expected when
instances of your
processes are run in the
runtime environment.
If IBM Business Monitor is
installed, its tracking
definitions (part of a
monitor model) are
automatically updated as
well.

There is no need to send


tracking definitions unless
a problem occurs during
snapshot deployment. If a
problem does occur, you
can select the Update
Tracking Definitions
option for the snapshot in
the Process Admin
Console.

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.

Parent topic:Enabling processes for tracking and reporting

405

Exposing performance scoreboards


The performance scoreboards are not exposed by default. If you want to expose
them to your Process Portal users, you must complete some manual steps.

Before you begin


To perform this task, you must be in the IBM Process Designer desktop editor.

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

Defining reports in Process Designer (deprecated)


Reports enable you to analyze business data that is specific to your processes. You
can specify the variables to track and define the report to query your tracked data.
Users can view the resulting report scoreboards from the Dashboards page in
Process Portal. Instead of using the deprecated reporting capabilities, consider
using dashboards that you design in Coaches.

Before you begin


The reporting functionality is deprecated in IBM BPM V8; by default it is not
enabled. To enable reporting, in Process Designer go to File > Preferences > IBM
BPM > Capabilities, and enable the Backward Compatibility capabilities.
To perform this task, you must be in the IBM Process Designer desktop editor.
Ensure that autotracking is enabled for the business process definition (BPD).
Ensure that the tracked data is current by selecting File > Update tracking
definitions.

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.

- Defining a custom layout Process Designer for reports (deprecated)


When you define a report in Process Designer, you can select an existing chart
layout (for example, one of the layout included in the System Data toolkit), to
display resulting data, or you can create a custom layout.
Parent topic:Enabling processes for tracking and reporting
Related tasks:
Configuring runtime teams

408

Defining a custom layout Process Designer for reports


(deprecated)
When you define a report in Process Designer, you can select an existing chart
layout (for example, one of the layout included in the System Data toolkit), to display
resulting data, or you can create a custom layout.

Before you begin


To perform this task, you must be in the IBM Process Designer desktop editor.

About this task


The reporting functionality is deprecated in IBM BPM V8; by default it is not enabled.
To enable reporting, in Process Designer go to File > Preferences > IBM BPM >
Capabilities, and enable the Backward Compatibility capabilities.
Creating a custom chart type enables you to control the format of your report results.
For example, the chart types available by default in the System Data Toolkit may not
meet the needs of your users. Or, you may want to develop customized chart types
to meet corporate guidelines.

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.

Case management overview


IBM Business Process Manager is a case management system that simplifies the
job of designing and building cases. It also provides a graphical user interface for
case workers to manage cases. With IBM Business Process Manager, you design
410

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

Case artifacts and the IBM BPM content store


The IBM BPM content store contains the
generated case folder and
document definitions and the case artifacts.
Parent topic:Building process applications

412

Case management overview


IBM Business Process Manager is a case management system that simplifies the
job of designing and building cases. It also provides a graphical user interface for
case workers to manage cases. With IBM Business Process Manager, you design 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.
Case management functions are only available if you have IBM BPM Advanced with
the Basic Case Management feature installed.
For example, if you want to design an application for resolving credit card disputes,
IBM Business Process Manager provides tools to design and create an application
that case workers can then use to process the cases that are created.
IBM Business Process Manager unifies information, processes, and people by
providing you with the following functions:
- An active-content infrastructure that manages the persisted case object model and
enables
content-based events for case activities. For example, the addition of a
document or a field
change triggers a case activity.
- Enterprise Content Management integration that includes complete document
lifecycle
capabilities. These capabilities include creating a version and security.
Some licensing
restrictions might apply.
- True content management functions to store document metadata that you can
modify and search
on.
- A process that manages the logic for running a sequence of activities.
- An out of the box user interface that is flexible and customizable. You can use the
user
interface to create a team-based experience that provides case workers
with the information
they must work on.
For a high-level overview of how IBM Business Process Manager handles cases,
watch this short overview video available on YouTube or in the IBM Education
Assistant information center. A transcript of the video is available.
-

Case management concepts


Case management applications consist of case types, document types, human
services,
and other components. A case management application is an
application that case workers use to
process cases.
Scenario: Financial services credit card dispute resolution
IBM Business Process Manager can provide card-issuing banks with a case
management application for credit card dispute resolution. IBM Business Process
Manager provides a comprehensive view of the case for the case workers. It
improves case worker efficiency and reduces the chance for errors as the case is
being processed.
Scenario: Automobile insurance claims
IBM Business Process Manager can provide an application for creating and
managing automobile insurance claims. With the case management system, you
can associate the data about the claim and the submitter with the supporting
documentation as it is submitted. The business analyst can quickly process any

413

required changes to the automobile claim solution. By configuring an application


in IBM Business Process Manager, you can ensure that claims are processed
completely and accurately.
Parent topic:
Building cases
Related concepts:
Designing a case application
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

414

Case management concepts


Case management applications consist of case types, document types, human
services,
and other components. A case management application is an
application that case workers use to
process cases.
Case management functions are only available if you have IBM BPM Advanced with
the Basic Case Management feature installed.

- 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:

Case management overview

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

Scenario: Financial services credit card


dispute resolution
IBM Business Process Manager can provide card-issuing banks with a case
management application for credit card dispute resolution. IBM Business Process
Manager provides a comprehensive view of the case for the case workers. It
improves case worker efficiency and reduces the chance for errors as the case is
being processed.
Case management functions are only available if you have IBM BPM Advanced with
the Basic Case Management feature installed.

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

is automatically added to the case as a document.


Frank uses Process Portal as an interface. This interface is customized to Frank's
job as a case worker. The interface provides a comprehensive view of the case.
The tools to review details of the case are readily available and actions can be
taken based on the findings. After some research, Frank discovers that the
merchant is out of business. Frank adds a comment to the case about this
discovery. Frank is notified that the online receipt and delivery agreement from
Jane are available. These documents automatically get added to the case and
are ready for Frank to review.
Frank decides to process a chargeback against the merchant. Frank starts an
activity that gathers the relevant details of the case. The activity formulates the
chargeback request, validates that the information is correct and complete, and
forwards it to the credit card company. Frank also creates an activity in the case
for Frank's supervisor Richard to review the case. Richard can then determine
whether any action must be taken based on the fact that the merchant is no
longer in business.
Frank's supervisor Richard reviews the case. Richard notices Frank's comment that
the merchant is out of business. Richard also analyzes recent transactions that
involve the merchant to determine the bank's level of exposure.
Based on this analysis, Richard decides to set up a subteam to handle any disputes
that involve this merchant. Richard sends a change request to Anna, who is the
business analyst, to modify the application to incorporate this new team. From
Richard's Process Portal environment, Richard requests that a letter is sent to
affected customers to inform them of their dispute rights. Richard also sends an
alert to the team of advisors to inform them of the situation. Richard then completes
the review of the case.
Anna receives Richard's change request. To satisfy the new requirement, Anna
designs a new team for the subteam in the application and a new rule. When
customers call with disputes that involve this merchant, the new rule routes the
disputes to the new team. By using the IBM Business Process Manager tools, Anna
can implement the changes in a few minutes. Anna can then easily test the
changes before Anna deploys the changes to the production system.
Because the credit card company implemented an efficient case management
process, Jane's and other customer's requests can be more quickly resolved.

Parent topic:

Case management overview

Related concepts:
Case management concepts

419

Scenario: Automobile insurance claims


IBM Business Process Manager can provide an application for creating and
managing automobile insurance claims. With the case management system, you
can associate the data about the claim and the submitter with the supporting
documentation as it is submitted. The business analyst can quickly process any
required changes to the automobile claim solution. By configuring an application in
IBM Business Process Manager, you can ensure that claims are processed
completely and accurately.
Case management functions are only available if you have IBM BPM Advanced with
the Basic Case Management feature installed.

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:

Case management overview

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

Opening Case Designer from Process

You can configure process applications and toolkits so that users can open them in
Case Designer from Process Center.

About this task


Case management functions are only available if you have IBM BPM Advanced with
the Basic Case Management feature installed.
If you configure a process application or toolkit so that users can open it in Case
Designer, a link Open in Case Designer is displayed in 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

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.

About this task


Case management functions are only available if you have IBM BPM Advanced with
the Basic Case Management feature installed.
You create a case type from the Cases category in the library. Note:You can use
only the Case Type editor to update a case type; that is, you cannot use an
external tool.

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

Configuring how a case is started


A case can be started manually by an authorized user or automatically when a
document of a specified type is added to the IBM BPM content store. You can
configure a case type to support both of these starting mechanisms. For example,
a case might start when a customer submits an online complaint form or when a
customer service representative initiates the case in response to a customer call.
Adding a case type variable or property
A variable contains information that can be shared among activities. A case folder
property is a variable whose value is stored in the case folder and thus also visible
to anyone directly interacting with the case folder.
Adding case type folders
Folders provide a way of grouping documents that are related to a case. You can
create a folder structure that case workers in Process Portal can use to add
documents that are required to complete the case. You create case folders in the
case type editor.
Assigning teams to a case type
You can assign a team whose members can start a case, or an instance owners
team whose members can work with the case at run time in Process Portal.
Parent topic:
Building cases
Related concepts:
Case management overview
Designing a case application
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

426

Configuring how a case is started


A case can be started manually by an authorized user or automatically when a
document of a specified type is added to the IBM BPM content store. You can
configure a case type to support both of these starting mechanisms. For example,
a case might start when a customer submits an online complaint form or when a
customer service representative initiates the case in response to a customer call.

About this task


Case management functions are only available if you have IBM BPM Advanced with
the Basic Case Management feature installed.

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:

Creating a case type

Related tasks:

427

Assigning teams to a case type

428

Adding a case type variable or property


A variable contains information that can be shared among activities. A case folder
property is a variable whose value is stored in the case folder and thus also visible
to anyone directly interacting with the case folder.

About this task


Case management functions are only available if you have IBM BPM Advanced with
the Basic Case Management feature installed.
A variable can have a primitive type such as a String. A variable can also be a
business object with either a complex or simple type. A case folder 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.

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:

Creating a case type

Related information:
Creating custom business objects in Process Designer
Data mapping in Enterprise Content Management operations

430

Adding case type folders


Folders provide a way of grouping documents that are related to a case. You can
create a folder structure that case workers in Process Portal can use to add
documents that are required to complete the case. You create case folders in the
case type editor.

About this task


Case management functions are only available if you have IBM BPM Advanced with
the Basic Case Management feature installed.
Adding folders is a way to group logically related documents similar to paper folders
in a desk. In a large, complex case, folders bring order to the many documents
that accumulate over the resolution of the business problem. A folder can contain
one or more subfolders.
A case itself has a folder. The folders that you define for the case type are the initial
set of folders that are automatically created when a case is started. At run time,
you can add or remove subfolders under a specific case folder. In addition to
Process Portal, case folders can also be accessed in the IBM BPM content store.

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:

Creating a case type

432

Assigning teams to a case type


You can assign a team whose members can start a case, or an instance owners
team whose members can work with the case at run time in Process Portal.

About this task


Case management functions are only available if you have IBM BPM Advanced with
the Basic Case Management feature installed.
You develop your case type in the Case Type editor. At run time, you can start an
instance of the case type, and case workers can view and start the case activities
in the activity list in Process Portal. The Expose to start option determines the
users who can start the instance in the Launch area in Process Portal. The
instance owner team identifies the users who can work with the case. For
example, for the Manage Dispute case type you might create a case owner team
called Customer Service Representatives.

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:

Creating a case type

Related tasks:
Configuring how a case is started

433

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.

About this task


Case management functions are only available if you have IBM BPM Advanced with
the Basic Case Management feature installed.
To simplify a workflow, you can also break a large activity into smaller, more
manageable
activities. For example, instead of having a single activity for the
credit card dispute,
you might have the following activities:
- Receiving a form from a customer
- Initiating a case
- Tracking the status of a case
- Reviewing a document
- Requesting a copy of the sales receipt
- Opening a dispute claim
- Opening a fraud investigation
- Generating correspondence related to the dispute
- Requesting a document
The case is not complete until all the required activities are completed and all
running
activities are completed.

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

A required activity must be


completed before the case can
complete. A
required
activity can be started
automatically or manually as
soon as the case is
created or after preconditions
are met for the activity. For
example, your solution
for credit card disputes has a
case type for claims with
supporting documentation.
You can create a required
activity for a claim review as
soon as supporting
documentation for a claim is
added to the content store.
Optional
An optional activity is created
as needed. An optional activity
can be
started
automatically, or manually as
soon as the case is created or
after
preconditions
are met for the activity. For
example, your solution for
automobile
claims
has a case type for automobile
accidents. You can create an
optional activity
that
can be manually started for the
rental car task.
3. Enter a name for the activity and optionally add a description in the
Documentation field.
Next, define the behavior of the activity, in the Behavior
section of the General
page.
1. Define how the activity is started:
Option
Automatically

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

2. The behavior section provides another way to set an activity as required or


optional.
If you change the setting here, the activity moves into the
appropriate section.
3. If the activity can be invoked multiple times, select
Repeatable. You can
mark an activity to repeat when there is a
property change or when a
document-filing precondition is defined for the activity. An
activity that is
marked as repeatable can occur multiple times during the lifetime of the
case it is part of and can cause new activities to be created and repeated.
Activities can
be repeated as needed, even if the activity already
completed.
4. You can hide activities from users in Process Portal. If the activity is a background
activity that users should not see, select Hidden. Hidden
activities
can be started automatically or manually as soon as the case is created or
after the preconditions are met for the activity. The activity does not appear in the
Activities section in the Process Portal, but assigned users can view and
work with
resulting tasks in the Process Portal task lists. Typically, hidden
activities are
automatic but they can also be manual. A manual hidden
activity can be started only programmatically, by using the
ActivityInstance.start() method. For more information, see JavaScript API
for IBM Process Designer and REST API for the Activity Instance (Ad Hoc)
Resource.
Define when the activity is ready to start by setting preconditions. Activities
can
start automatically after all the preconditions are met or manually by a user after all
the preconditions are met. If you do not set any preconditions, automatic
activities start
as soon as the case is launched and manual activities must be
started by a user. See Setting preconditions.
1. Define the implementation for the activity and map the data if it is required.
-

Setting preconditions for case activities


You can specify preconditions that must be met before the activity is ready to
start. Activities can start automatically after all the preconditions are met or
manually by a user after all the preconditions are met. If you do not set any
preconditions, automatic activities start as soon as the case is launched and
manual activities must be started by a user.
Implementing a case activity
Case activities can be implemented with a linked process, a subprocess, or a
client-side human service.
Parent topic:
Building cases
Related tasks:
Implementing an activity

436

Setting preconditions for case activities


You can specify preconditions that must be met before the activity is ready to start.
Activities can start automatically after all the preconditions are met or manually by a
user after all the preconditions are met. If you do not set any preconditions,
automatic activities start as soon as the case is launched and manual activities
must be started by a user.

About this task


Case management functions are only available if you have IBM BPM Advanced with
the Basic Case Management feature installed.
A precondition consists of two parts, a precondition event, and a precondition
expression. The two parts together determine when the activity starts:
- If both are defined, then when the precondition event occurs, the precondition
expression
is evaluated. If the expression evaluates to true, the activity starts.
- If there is a precondition event but no precondition expression, the activity starts
when
the precondition event is met.
Note: In addition to determining
when the activity first starts, the precondition
also determines when an activity that is
already started changes state. For
example, from a waiting state to a working state. See
Runtime states for
activities in process applications.

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

A document is filed in the


case

The activity starts when a


document is added to the case.
Any document typeThe
activity starts when a document
is added to the case. This
option applies to all
documents, including
documents that are not
contained in this process
application.Choose one or
more document typesThe
activity starts when a document
of any of the specified
document types is added to
the case.Inside the
implementation of the activity,
you can use JavaScript to
access the
identifier of the
document that caused the
activity to start:

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:

Adding a case activity


438

439

Implementing a case activity


Case activities can be implemented with a linked process, a subprocess, or a
client-side human service.

About this task


Case management functions are only available if you have IBM BPM Advanced with
the Basic Case Management feature installed.

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

that is implemented as a subprocess, multiple


instances of
the subprocess might be active at the same time (for
example, when multiple documents arrive within a short time period).
These instances concurrently access the same case variables and can
therefore interfere with each other.
- Linked ProcessSelect an existing linked
process as the
implementation. Working with linked processesNote: You cannot create a linked
process from the case type
editor. To create a linked
process, start the Process Designer
desktop editor.
4. For client-side human services and linked processes, you must map the case
variables to the client-side human service or linked process variables.
Data
mapping maps the case type input and output variables to the
input and output
variables of the client-side human service or linked
process. In some
client-side human services, the mapping is
complete since the wizard to create a
human service creates the
mapping as one of its steps. To create a data
map:
A. Click the Data Mapping tab.
B. For input mapping, click the select a variable icon ( ). Select the input case
type variable to map to the input variable from the linked process
or
human process. Then, repeat this procedure for the output
variables.
Subprocesses have direct access to the case variables and therefore do not
need data mapping.
5. Save your work.
Parent topic:

Adding a case activity

Related tasks:
Adding a case activity
Related information:
Subprocess types
Client-side human services
Building a client-side human service
Creating a team

441

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

About this task


Case management functions are only available if you have IBM BPM Advanced with
the Basic Case Management feature installed.
You create a document type from the Cases category in the library.

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.

Example 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.
Parent topic:
Building cases
Related concepts:
Case management overview
Designing a case application
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
Related information:
cleanupDocumentStoreProperties command

443

Example 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.
Case management functions are only available if you have IBM BPM Advanced with
the Basic Case Management feature installed.
You define document types to group similar documents and the information about
the documents that are related to the case. You can create as many document
types and properties as needed.
For example, an automobile claim case might have these document types and
properties.
Table 1. Examples of automobile claim document types and properties
Document type and description

Properties that are related to this


document type
Policy documents, such as the written
Deductible amount, effective date of the
automobile policy and formal changes to policy, expiration date of policy, policy
the
policy
number, policy type, vehicle identification
Application forms, such as the initial
Customer address, customer given
written application form
name, customer surname, customer
phone number, date
of application,
policy number, policy type, vehicle
identification
Claim forms, such as a claim for a
Claim number, date of loss, policy
broken windshield
number, type of loss, vehicle
identification
Repair estimation documents, such as an Claim number, customer given name,
estimate for a new windshield from a
customer surname, estimate total, repair
glass
repair company
item,
vendor name
Damage assessment documents, such Claim number, customer given name,
as the report from insurance claim
customer surname, date of loss, vehicle
evaluator or
photographs of the
identification, vehicle replacement value
damaged windshield
Correspondence, such as letters sent to Claim number, customer given name,
the customer about the claim
customer surname, date of loss, vehicle
identification
Proof of ownership, such as the
Claim number, customer given name,
automobile registration from a state
customer surname, date of loss, vehicle
licensing agency
or a bill of sale
identification, vehicle license plate
number

Parent topic:

Creating a document type

444

Creating case user interfaces


Create user interfaces that a user sees for the case instance in Process Portal.

About this task


Case management functions are only available if you have IBM BPM Advanced with
the Basic Case Management feature installed.
IBM Business Process Manager provides a user interface for your instances in
Process Portal. You can either use the provided interface or you can create your
own user interface and make it the default user interface for all users. Optionally,
you can also create your own user interface that is customized for instance owners.
Attention: A process instance user interface must be implemented as a client-side
human service. You cannot implement it as a heritage human service.
You can create these user interfaces:
- The Default user interface that overrides the user interface that is provided by
IBM BPM. Any user that has permission to see the process instance in Process
Portal will see this interface. You can create a client-side human service and
specify it as the user interface. If you do not specify a client-side human service
here, the user interface that is provided by IBM BPM is used.
- The Instance Owners user interface is an optional user interface that you can
create for the team that is specified in the Instance owner team field in the
Overview page. You can create a client-side human service and specify it as the
user interface for the instance owners.
- The Launch UIDefault user interface is seen by members of the team that is
assigned to the Expose to start option in the
Overview page.

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

You can, however, add


private variables that are available only to the
human service. If you are creating a
launch case UI, Process Designer
generates a cancelCase variable of
type Boolean. The default value is
false. You can only view this variable, you cannot
change or delete it. The
value of the variable is set by the launch UI human service. If
the value of
cancelCase is true when a user completes the human
service during case
launch, the launch is canceled. If the value is false, the case is
started.
6. Switch to the Diagram page. A basic diagram is generated for
you.
7. Double-click the coach to open the Coaches page.
8. Complete the human service diagram and customize the coaches.
- For a Details UI, the generated human service has two
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 human
service.
- Show error, which returns an error if the instance is not
found.
The human service is generated from a template in the Dashboards toolkit,
called
Instance Details UI Services Template. For more information, see
Instance Details UI Service template
- For a Launch UI, the generated human service has an
Enter Data
coach, with a control for each mapped case type
variable and property.
When you specify a launch case UI, Process Designer generates a
cancelCase variable of type Boolean. The value of the variable is
set by
the launch UI human service. If the value of cancelCase is
true when a
user completes the launch case human service, the launch is canceled. If the
value of cancelCase value is false, the case is started. The default
value is false. The generated Launch UI has one coach with two buttons;
OK and Cancel. If a user clicks
Cancel, the cancelCase variable is set
to
true. If you are working with the IBM BPM content store on an
Enterprise Content
Manager server, you can modify your Launch UI so
that a user can view or add documents
in the case folder that you
specified in the Folders page. To do
so, use coach controls that are
provided in the Content Management toolkit for viewing
and retrieving
documents in the content store. For example, the Document
Explorer control. These controls are available in the Content Management
toolkit. For more information, see:
- How to use coach views to store or view documents
- Document Explorer control
Note: If the case launch is canceled, the case folder is removed from the IBM
BPM
content store. Documents that are also used outside the case
folder remain in the
content store. Otherwise, they are removed.
9. Test the client-side human service.
- For Launch UI, click Run
to test the client-side human
coach.
446

service and the

- For Details UI, do one of the following:


- If the human service flow is not customized, run the instance UI within Process
Portal.
- If you want to incrementally test and build your custom UI:
A. Remove the logic in the human service that shows an error if the process
instance id is null.
B. Add a script task to insert some temporary test data.
C. Run the human service
D. After you are satisfied that the service works as expected, remove the
temporary script and then test again by running the instance UI within
Process
Portal.

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

Testing and debugging a case type


Play back your case type in the Inspector to test and debug your activities.
Case management functions are only available if you have IBM BPM Advanced with
the Basic Case Management feature installed.
You can test and debug your case type in the Inspector to test your activities. You
can run and debug the implementations of your activities; human services,
subprocesses and linked processes. Depending on the type of activity, you start
the Inspector from the Process Designer web editor or the Process Designer
desktop editor.

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.

User task activities


You can test and debug a user task activity by running the client-side human
service that implements the activity.
1. Open the case type and drill into the activity to open the client-side human
service.
2. Depending on whether you are testing or solving a problem, click Run
or
Debug. See Running and debugging client-side human services.

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

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.
Case management functions are only available if you have IBM BPM Advanced with
the Basic Case Management feature installed.
A service to support a case management application uses its own server type. The
server type is IBM BPM content store.
IBM BPM content store
supports all
Content Management Interoperability Services (CMIS)
operations.
Add the Content Management (SYSCM) toolkit to your dependencies if it is not
there,
as you need access to the Enterprise Content Management (ECM)
types. To add this
toolkit dependency, select + beside
TOOLKITS. In the Add dependency
menu, select the Content
Management toolkit version that you
require.
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. Select
IBM BPM content store
to create a case service.
4. Under Content Operation, select an appropriate ECM
operation.
5. Click Data Mapping. Create the map between the
variables for
input and output. These variables must 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 ( ). The mapping structure for each operation is
shown in Data mapping in Enterprise Content Management operations.
6. Save your work to update the process application with any changes to your
service.

450

Enterprise Content Management operations can reference the content of a case by


using
JavaScript. Table 1. Referencing content of a case by using
JavaScript
Content or function referenced
Accessing the case folder

JavaScript required in the Enterprise


Content Management
operation
Requires the
tw.system.currentProcessInstance.c
aseFolderId

Accessing the starting document of a


case

Accessing the enabling document of a


case activity

JavaScript API, which contains the


identifier of the root case
folder.
Requires the
tw.system.currentProcessInstance.s
tartingDocumentId

JavaScript API, which contains the


identifier of the document
that initiated the start of the case. If the
case was started
manually, the identifier is null.
Requires the
tw.system.currentAdHocActivityInst
ance.enablingDocumentID

JavaScript API, which contains the


identifier of the document
that started or enabled the case activity.
The identifier is
null for activities not started by a
precondition of a document
filed in the case.
Creating a subfolder under a case folder Every subfolder of the case folder must
be of type
IBM_BPM_CaseSubFolder. You must
specify
this type in
the Object type ID parameter of the
Create Folder
operation.

Parent topic:

Building cases

Related concepts:
Case management overview
Designing a case application
Related tasks:
Creating a process application for your case types
451

Creating a case type


Creating a document type
Related information:
Outbound interactions with Enterprise Content Management systems
Inbound events from Enterprise Content Management systems

452

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.
Case management functions are only available if you have IBM BPM Advanced with
the Basic Case Management feature installed.
Parent topic:

Building cases

453

store

Case artifacts and the IBM BPM content

The IBM BPM content store contains the


generated case folder and
document definitions and the case artifacts.
Case management functions are only available if you have IBM BPM Advanced with
the Basic Case Management feature installed.
Case artifacts are created or updated in the IBM BPM content store in the following
ways:
- When a playback occurs, that is, a case starts or a document is created in
Process Portal. This
takes place in the Process Center.
- When a TWX file is imported into the Process Center.
- When a snapshot is taken in the Process Center.
- When a snapshot is installed on the Process Server.
- When the document type is used in either a Content Integration step or event
subscription that target the IBM BPM content store. The selection
of the document type in the Process Center causes the
update.

Behavior of the IBM BPM content store


In IBM Business Process Manager, a business
process definition or a
case starts from the tip or a named snapshot. However, a
case not only
consists of the activities that are run like a business process
definition, but
a case also has a case folder. The case folder is a separate
artifact that is
created in the IBM BPM content store for each case instance.
For each
case type, there is also a case folder definition in the IBM BPM content store. It is
kept in
synchronization with the case folder properties defined in the case
type.
Unlike the IBM Business Process Manager
repository, the IBM BPM
content store
does not save different versions of a case folder definition.
Instead, all case
folder properties that are defined in all snapshots and the
tip are available in one
case folder definition. At run time, changes to
variables that are made in
activities that use case folder properties are
automatically synchronized to the
case folder instance. Changes to the
properties on the case folder instance are
automatically synchronized
back to the case instance, potentially causing a
precondition change.
For document types, there is one document class definition in the IBM BPM content
store that has all properties
that are defined on all snapshots and the tip.

Cleaning up properties and removing case folder instances


For both case types and document types, a property might still be available in the
deployed definition in the IBM BPM content store although it is not
available in any snapshot or tip. This situation can happen if you deleted
snapshots. It can also happen if you had a property on a tip and then deleted the
property without taking a snapshot. For example, you have a snapshot that
contains
two case type properties. You continue to develop your

454

application that is now on


the tip. You remove one of the properties but do
not take a snapshot. The property
that you removed is still available in the
corresponding IBM BPM content store artifact definition. To
clean up
these properties, use the cleanupDocumentStoreProperties command. See the
related links at the end of the topic.
While a case folder is automatically created when a case instance is started, it is
not cleaned up when the instance is finished and deleted. The case folder, its
properties, and contained documents are kept for archival purposes. You
need to explicitly remove them, for example, by using the IBM Administration
Console for Content Platform Engine. The only exception to this rule is
the
removal of a process application in the Process Center. With the removal of the
process application, all case folders and documents that belong to that process
application are removed.

Update restrictions for modifying case 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.
Parent topic:
Building cases
Related reference:
Redeployment restrictions for modifying a process application
Related information:
Cleaning up the IBM BPM document store
cleanupDocumentStoreProperties command
Limitations in administering the IBM BPM document store

455

artifacts

Update restrictions for modifying case

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

The item is not


removed from the
IBM BPM content
store.
Existing items can be See the Type of
affected.
changes column for
the Required property
setting for document
type properties.
No issues.
The property is not
removed from the
corresponding class
in the IBM BPM
content store.
When working with a
document or case
folder using the
Enterprise Content
Management
integration tools, the
old property will
continue to be
available.

456

Change the name of No issues.


a business object that
is associated with a
case type or
document type
property.

Change the
cardinality of a
document type or
case type property
definition.

No issues.

Change the property Existing items are


definition description affected.
in a case type or
document type.

457

The business object


change results in the
addition of a new
property to the
corresponding class
in the IBM BPM
content store. The old
property
corresponding to the
original version is not
removed from the
class definition.
When working with a
document or case
folder using the
Enterprise Content
Management
integration tools, the
old property will
continue to be
available.
The cardinality
change results in the
addition of a new
(multi or single value)
property to the
corresponding class
in the IBM BPM
content store. The old
property
corresponding to the
original version is not
removed from the
class
definition.
When working with a
document or case
folder using the
Enterprise Content
Management
integration tools, the
old property will
continue to be
available.
All existing and new
instances of a case
and document class
in the IBM BPM
content store use the
updated
property description.

The validation
settings for a simple
type business object
that is used in a
case type or
document type
property

Some existing items


are affected. This
method changes the
metadata of the
underlying property
template. As a result,
this change affects all
document
classes that use the
same business object
in a property
definition.
Case folder classes
are unaffected by the
validation settings
change with one
exception. Changing
the maximum length
of a string business
object might reset
the maximum length
of the corresponding
string property for all
case type
definitions that
reference the same
business object. The
value is set to the
greater of the existing
and new values.
None of the other
validation setting
values are set in the
corresponding case
folder class property.
However, the
validation setting
values are enforced
by
the
Business Process
Manager engine at
run time.

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:

Case artifacts and the IBM BPM content store

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 rel