Sunteți pe pagina 1din 732

WebSphere Process Server for Multiplatforms

Version 6.1.2

Business Process Choreographer



WebSphere Process Server for Multiplatforms

Version 6.1.2

Business Process Choreographer



Note
Before using this information, be sure to read the general information in the Notices section at the end of this document.

27 June 2008
This edition applies to version 6, release 1, modification 2 of WebSphere Process Server for Multiplatforms (product
number 5724-L01) and to all subsequent releases and modifications until otherwise indicated in new editions.
To send us your comments about this document, send an e-mail message to doc-comments@us.ibm.com. We look
forward to hearing from you.
When you send information to IBM, you grant IBM a nonexclusive right to use or distribute the information in any
way it believes appropriate without incurring any obligation to you.
Copyright International Business Machines Corporation 2006, 2008. All rights reserved.
US Government Users Restricted Rights Use, duplication or disclosure restricted by GSA ADP Schedule Contract
with IBM Corp.

Contents
Part 1. Business processes and
human tasks in WebSphere Process
Server . . . . . . . . . . . . . . . 1
Chapter 1. About business processes . . 3
Process templates . . . . . . . . . . . . . 4
Business process types . . . . . . . . . . 4
Process versioning . . . . . . . . . . . 5
Process instances . . . . . . . . . . . . . 6
Process life cycle . . . . . . . . . . . . . 6
State transition diagrams for process instances . . 6
Life cycle management of subprocesses . . . . 9
State transition diagram for activities . . . . . 9
Invocation scenarios for business processes . . . . 17
Factors affecting business process interactions . . 18
Dynamic binding between business processes
and SCA services . . . . . . . . . . . 19
Late binding of processes . . . . . . . . . 19
Passing parameters between business processes
and services . . . . . . . . . . . . . 19
Transactional behavior of business processes . . . 20
Transactional behavior of microflows . . . . . 21
Transactional behavior of long-running processes 23
Fault handling and compensation handling in
business processes . . . . . . . . . . . . 26
Fault handling in business processes . . . . . 27
Compensation in business processes . . . . . 30
Recovery from infrastructure failures . . . . . 32
Authorization and people assignment for processes 34
Authorization roles for business processes . . . 34
Authorization for creating and starting business
processes . . . . . . . . . . . . . . 37
Authorization for interacting with a business
process . . . . . . . . . . . . . . . 38
Authorization for administering business
processes . . . . . . . . . . . . . . 38

Chapter 2. About human tasks . . . . 41


Task templates . . . . . . . . . . . . .
Kinds of human tasks . . . . . . . . . .
Versioning of human tasks . . . . . . . .
Task instances . . . . . . . . . . . . .
Stand-alone and inline tasks . . . . . . . . .
Subtasks . . . . . . . . . . . . . . .
Follow-on tasks . . . . . . . . . . . . .
Escalations . . . . . . . . . . . . . .
E-mail notifications for escalations . . . . . .
Life cycle of human tasks . . . . . . . . . .
Scenarios for invoking tasks . . . . . . . . .
Factors affecting the behavior of stand-alone
invocation tasks and their service components . .
Scenario: stand-alone invocation tasks that
support the asynchronous invocations of services .

Copyright IBM Corp. 2006, 2008

41
41
42
43
44
48
50
52
54
55
59
62
63

Scenario: stand-alone invocation tasks that


support asynchronous and synchronous
invocations of services . . . . . . . . . .
Authorization and people assignment . . . . .
Authorization roles for human tasks . . . . .
Authorization and work items . . . . . . .
People assignment criteria . . . . . . . .
People resolution . . . . . . . . . . .
Substitution for absentees. . . . . . . . .
Default people assignments and inheritance rules
Managing people assignment criteria and people
resolution results . . . . . . . . . . .
Sharing people assignments . . . . . . . .

65
68
68
70
71
81
88
88
90
91

Part 2. Planning and configuring


Business Process Choreographer . 93
Chapter 3. Planning to configure
Business Process Choreographer . . . 95
Planning the topology, setup, and configuration
path . . . . . . . . . . . . . . . . . 95
Planning for a remote client application . . . 100
Planning to create a basic sample Business Process
Choreographer configuration . . . . . . . . 101
Planning to create a sample Business Process
Choreographer configuration including a sample
organization . . . . . . . . . . . . . . 102
Planning a non-production deployment
environment configuration . . . . . . . . . 103
Planning to use the administrative consoles
deployment environment wizard . . . . . . . 104
Planning for a custom Business Process
Choreographer configuration . . . . . . . . 109
Planning security, user IDs, and authorizations 110
Planning the databases for Business Process
Choreographer . . . . . . . . . . . . 116
Planning for the Business Flow Manager and
Human Task Manager . . . . . . . . . 128
Planning for the people directory provider . . 130
Planning for the Business Process
Choreographer Explorer . . . . . . . . . 132
Planning for the Business Process
Choreographer Observer . . . . . . . . 132
About Business Process Choreographer . . . . . 135
About Business Process Choreographer Explorer 136
About Business Process Choreographer
Observer . . . . . . . . . . . . . . 137

Chapter 4. Configuring Business


Process Choreographer . . . . . . . 141
Using the Installer or Profile Management Tool to
configure Business Process Choreographer . . . 141

iii

Using the administrative consoles deployment


environment wizard to configure Business Process
Choreographer . . . . . . . . . . . . .
Using the administrative consoles Business Process
Choreographer configuration page . . . . . .
Using the bpeconfig.jacl script to configure
Business Process Choreographer . . . . . . .
bpeconfig.jacl script file . . . . . . . . .
Creating the queue manager and queues for
Business Process Choreographer . . . . . .
Using a generated SQL script to create the
database schema for Business Process
Choreographer . . . . . . . . . . . .
Using SQL scripts to create the database for
Business Process Choreographer . . . . . . .
Creating a Derby database for Business Process
Choreographer . . . . . . . . . . . .
Creating a DB2 for i5/OS database for Business
Process Choreographer . . . . . . . . .
Creating a DB2 for Linux, UNIX, and Windows
database for Business Process Choreographer . .
Creating a DB2 for z/OS database for Business
Process Choreographer . . . . . . . . .
Creating an Informix Dynamic Server database
for Business Process Choreographer . . . . .
Creating a Microsoft SQL Server database for
Business Process Choreographer . . . . . .
Creating an Oracle database for Business
Process Choreographer . . . . . . . . .
Configuring the people directory provider . . . .
Configuring the Virtual Member Manager
people directory provider . . . . . . . .
Configuring the LDAP people directory
provider . . . . . . . . . . . . . .
Configuring people substitution . . . . . . .
Configuring Business Process Choreographer
Explorer . . . . . . . . . . . . . . .
Using the administrative console to configure
the Business Process Choreographer Explorer. .
Using the clientconfig.jacl script file to configure
the Business Process Choreographer Explorer. .
Configuring the Business Process Choreographer
Observer . . . . . . . . . . . . . . .
Removing the Business Process Choreographer
Observer Version 6.0.1 sample . . . . . . .
Preparing a database for the Business Process
Choreographer Observer . . . . . . . .
Selecting between Java and SQL user-defined
functions . . . . . . . . . . . . . .
Configuring the Business Process
Choreographer event collector application . . .
Configuring the Business Process
Choreographer Observer application . . . .
Enabling logging for Business Process
Choreographer . . . . . . . . . . . .
Changing configuration parameters for the
Business Process Choreographer Observer . . .
Verifying the Business Process Choreographer
Observer . . . . . . . . . . . . . .
Configuring a remote client application. . . . .
Activating Business Process Choreographer . . .

iv

Business Process Choreographer

144
147
150
157
172

176
180
181
182
183

Verifying that Business Process Choreographer


works . . . . . . . . . . . . . . . . 267
Understanding the startup behavior of Business
Process Choreographer . . . . . . . . . 268
Federating a stand-alone node that has Business
Process Choreographer configured . . . . . . 268

Chapter 5. Removing the Business


Process Choreographer configuration . 271
Using a script to remove the Business Process
Choreographer configuration . . . . . . .
Using tools to remove the Business Process
Choreographer Observer and event collector .
Using the administrative console to remove the
Business Process Choreographer configuration .
Using the administrative console to remove the
Business Process Choreographer event collector
Using the administrative console to remove
Business Process Choreographer Observer . .

. 271
. 274
. 275
. 280
. 281

Part 3. Administering . . . . . . . 283

185
187
189
190
192
192
194
199
202
203
204
207
207
208
239
245
249
251
253
262
263
267

Chapter 6. Administering Business


Process Choreographer . . . . . . . 285
Using the administrative console to administer
Business Process Choreographer . . . . . .
Administering the compensation service for a
server . . . . . . . . . . . . . .
Querying and replaying failed messages, using
the administrative console . . . . . . .
Refreshing people query results, using the
administrative console . . . . . . . .
Enabling Common Base Events and the audit
trail, using the administrative console . . .
Refreshing people query results, using the
refresh daemon . . . . . . . . . . .
Using scripts to administer Business Process
Choreographer . . . . . . . . . . . .
Deleting audit log entries, using administrative
scripts . . . . . . . . . . . . . .
Deleting process templates that are unused .
Deleting human task templates that are unused
Deleting completed process instances . . .
Deleting data from the observer database . .
Querying and replaying failed messages, using
administrative scripts . . . . . . . . .
Refreshing people query results, using
administrative scripts . . . . . . . . .
Removing unused people query results, using
administrative scripts . . . . . . . . .

. 285
. 285
. 285
. 287
. 288
. 290
. 290
. 291
. 293
295
. 298
. 300
. 302
. 306
. 308

Chapter 7. Getting started with


Business Process Choreographer
Explorer . . . . . . . . . . . . . . 311
Starting Business Process Choreographer Explorer 315
Customizing Business Process Choreographer
Explorer . . . . . . . . . . . . . . . 316

Customizing the Business Process


Choreographer Explorer interface for different
user groups . . . . . . . . . . . . . 316
Personalizing the Business Process
Choreographer Explorer interface . . . . . . 320
Changing the appearance of the default Web
application . . . . . . . . . . . . . 321

Chapter 8. Getting started with


Business Process Choreographer
Observer . . . . . . . . . . . . . 327
Chapter 9. Administering business
processes and human tasks . . . . . 333
Administering process templates and process
instances . . . . . . . . . . . . . . .
Stopping and starting process templates with
the administrative console . . . . . . . .
Stopping and starting process templates with
administrative scripts . . . . . . . . . .
Managing the process life cycle . . . . . .
Repairing processes and activities . . . . .
Administering task templates and task instances
Stopping and starting task templates with the
administrative console . . . . . . . . .
Stopping and starting task templates with the
administrative scripts . . . . . . . . . .
Creating and starting a task instance . . . .
Working on your tasks . . . . . . . . .
Suspending and resuming task instances . . .
Managing priorities of human tasks . . . . .
Managing work assignments . . . . . . .
Viewing task escalations . . . . . . . . .
Creating and editing custom properties in Business
Process Choreographer Explorer . . . . . . .
Reporting on business processes and activities . .
Using the predefined lists and charts . . . .
Creating user-defined reports . . . . . . .
Using saved user-defined report definitions . .

333
336
337
338
342
348
348
349
350
350
351
352
353
359
361
361
366
370
382

Part 4. Developing and deploying


modules . . . . . . . . . . . . . 387
Chapter 10. Developing client
applications for business processes
and tasks . . . . . . . . . . . . . 389
Comparison of the programming interfaces for
interacting with business processes and human
tasks . . . . . . . . . . . . . . .

. 389

Chapter 11. Developing EJB client


applications for business processes
and human tasks . . . . . . . . . . 391
Accessing the EJB APIs . . . . . . . . . .
Accessing the remote interface of the session
bean . . . . . . . . . . . . . . .
Accessing the local interface of the session bean
Querying business-process and task-related objects

392
392
395
397

Filtering data using variables in queries . . .


Managing stored queries . . . . . . . .
Developing applications for business processes . .
Required roles for actions on process instances
Required roles for actions on business-process
activities . . . . . . . . . . . . . .
Managing the life cycle of a business process
Processing human task activities . . . . . .
Processing a single person workflow . . . .
Sending a message to a waiting activity . . .
Handling events . . . . . . . . . . .
Analyzing the results of a process . . . . .
Repairing activities . . . . . . . . . .
BusinessFlowManagerService interface . . . .
Developing applications for human tasks . . . .
Starting an invocation task that invokes a
synchronous interface . . . . . . . . .
Starting an invocation task that invokes an
asynchronous interface . . . . . . . . .
Creating and starting a task instance . . . .
Processing to-do tasks or collaboration tasks . .
Suspending and resuming a task instance . . .
Analyzing the results of a task . . . . . .
Terminating a task instance . . . . . . . .
Deleting task instances . . . . . . . . .
Releasing a claimed task. . . . . . . . .
Managing work items . . . . . . . . .
Creating task templates and task instances at
runtime . . . . . . . . . . . . . .
HumanTaskManagerService interface . . . .
Developing applications for business processes and
human tasks . . . . . . . . . . . . . .
Determining the process templates or activities
that can be started . . . . . . . . . . .
Processing a single person workflow that
includes human tasks . . . . . . . . .
Handling exceptions and faults . . . . . . .
Handling API exceptions . . . . . . . .
Checking which fault is set for a human task
activity . . . . . . . . . . . . . .
Checking which fault occurred for a stopped
invoke activity . . . . . . . . . . . .
Checking which unhandled exception or fault
occurred for a failed process instance . . . .

410
411
414
414
415
416
423
424
426
427
428
428
430
433
433
434
435
436
437
438
439
439
439
440
441
448
451
452
454
456
456
457
457
458

Chapter 12. Developing Web service


API client applications . . . . . . . 461
Introduction: Web services . . . . . . . .
Web service components and sequence of control
Overview of the Web services APIs . . . . .
Requirements for business processes and human
tasks . . . . . . . . . . . . . . .
Developing client applications . . . . . . .
Copying artifacts . . . . . . . . . . .
Publishing and exporting artifacts from the
server environment . . . . . . . . .
Using files on the client CD . . . . . .
Developing client applications in the Java Web
services environment . . . . . . . . . .
Generating a proxy client (Java Web services)

. 461
461
. 462
. 463
. 463
. 463
. 464
. 469
. 472
472

Contents

Creating helper classes for BPEL processes (Java


Web services) . . . . . . . . . . . .
Creating a client application (Java Web services)
Adding security (Java Web services) . . . . .
Adding transaction support (Java Web services)
Developing client applications in the .NET
environment . . . . . . . . . . . . . .
Generating a proxy client (.NET) . . . . . .
Creating helper classes for BPEL processes
(.NET) . . . . . . . . . . . . . . .
Creating a client application (.NET) . . . . .
Adding security (.NET) . . . . . . . . .
Querying business-process and task-related objects
Queries on business-process and task-related
objects . . . . . . . . . . . . . . .
Predefined views for queries on
business-process and human-task objects . . .
Managing stored queries . . . . . . . .

475
477
477
481
481
482
483
485
486
487

Chapter 17. Installing business


process and human task applications . 537
Installing business process and human task
applications interactively . . . . . . .
Configuring process application data source
set reference settings . . . . . . . .
Uninstalling business process and human task
applications, using the administrative console
Uninstalling business process and human task
applications, using administrative commands

. . 539
and
. . 539
.

. 541

. 542

Part 5. Monitoring business


processes and tasks . . . . . . . 545

487
490
491

Chapter 18. Monitoring business


processes and human tasks . . . . . 547

Chapter 13. Developing JMS client


applications . . . . . . . . . . . . 493

Chapter 19. Monitoring business


process events . . . . . . . . . . 549

Introduction to JMS . . . . . . . . . . .
Requirements for business processes. . . . . .
Accessing the JMS interface . . . . . . . .
Structure of a Business Process Choreographer JMS
message . . . . . . . . . . . . . . .
Authorization for JMS renderings . . . . . .
Overview of the JMS API . . . . . . . . .
Developing JMS applications . . . . . . . .
Copying artifacts . . . . . . . . . . .
Checking the response message for business
exceptions . . . . . . . . . . . . .

Chapter 20. Monitoring human task


events . . . . . . . . . . . . . . 571

493
493
494
496
497
498
499
499
500

Event data specific to business processes .


Extension names for business process events
Business process events . . . . . . .
Situations in business process events . .

Event data specific to human tasks . .


Extension names for human task events
Human task events . . . . . . .
Situations in human task events . . .

.
.
.
.

.
.
.
.

.
.
.
.

.
.
.
.

.
.
.
.

.
.
.
.

.
.
.
.

549
549
560
569

571
571
575
578

Chapter 14. Developing Web


applications for business processes
and human tasks, using JSF
components . . . . . . . . . . . . 501

Part 6. Tuning . . . . . . . . . . 581

Adding the
Adding the
Adding the
application
Adding the
application

Tuning long-running processes . . . . . . .


Balancing the hardware resources . . . . .
Specifying initial DB2 database settings. . . .
Specifying initial Oracle database settings . . .
Planning messaging engine settings . . . . .
Tuning the application server . . . . . . .
Fine-tuning the Business Process Choreographer
database . . . . . . . . . . . . . .
Fine-tuning the messaging provider . . . . .
Improving the performance of business process
navigation . . . . . . . . . . . . .
Tuning microflows . . . . . . . . . . .
Tuning business processes that contain human
tasks . . . . . . . . . . . . . . . .
Reduce concurrent access to human tasks . . .
Reduce query response time . . . . . . .
Avoid scanning whole tables . . . . . . .
Optimize task and process queries . . . . .

List component to a JSF application


Details component to a JSF application
CommandBar component to a JSF
. . . . . . . . . . . . . .
Message component to a JSF
. . . . . . . . . . . . . .

506
513
515
519

Chapter 15. Developing JSP pages for


task and process messages . . . . . 523
User-defined JSP fragments .

. 524

Chapter 16. Creating plug-ins to


customize human task functionality. . 527
Creating API event handlers . . . . . . . .
Creating notification event handlers . . . . . .
Installing API event handler and notification event
handler plug-ins . . . . . . . . . . . .
Registering API event handler and notification
event handler plug-ins with task templates, task
models, and tasks . . . . . . . . . . . .
Creating and installing plug-ins to post-process
people query results . . . . . . . . . . .

vi

Business Process Choreographer

527
529
531

532
533

Chapter 21. Tuning business


processes . . . . . . . . . . . . . 583
584
584
586
589
589
590
591
596
596
598
598
598
599
599
600

Chapter 22. Tuning Business Process


Choreographer Explorer . . . . . . . 603

Chapter 23. Tuning Business Process


Choreographer Observer . . . . . . 605

Part 7. Troubleshooting . . . . . . 609


Chapter 24. Troubleshooting the
Business Process Choreographer
configuration . . . . . . . . . . . 611
Business Process Choreographer log files . . .
Troubleshooting the Business Process
Choreographer database and data source . . .
The URL for the REST API is not configured
correctly . . . . . . . . . . . . . .
6.0.x Business Process Choreographer API client
fails in a 6.1 environment . . . . . . . .
Enabling tracing for Business Process
Choreographer . . . . . . . . . . . .

. 611
. 612
. 614

Troubleshooting escalation e-mails . . . . .


Troubleshooting people assignment . . . . .
Troubleshooting Business Process Choreographer
Explorer . . . . . . . . . . . . . .
Troubleshooting Business Process Choreographer
Observer . . . . . . . . . . . . . .
Using process-related and task-related audit trail
information . . . . . . . . . . . . .
Audit event types for business processes . .
Audit event types for human tasks . . . .
Structure of the audit trail database view for
business processes . . . . . . . . . .
Structure of the audit trail database view for
human tasks . . . . . . . . . . . .

. 630
. 632
. 638
. 639
. 641
. 642
. 644
. 645
. 649

. 615

Part 8. Appendixes . . . . . . . . 653

. 616

Appendix A. Database views for


Business Process Choreographer . . 655

Chapter 25. Troubleshooting business


processes and human tasks . . . . . 617
Troubleshooting the installation of business process
and human task applications . . . . . . . .
Troubleshooting the uninstallation of business
process and human task applications . . . . .
Troubleshooting the execution of business
processes . . . . . . . . . . . . . . .
ClassCastException when stopping an
application containing a microflow . . . . .
Unexpected exception during invocation of the
processMessage method (message: CNTR0020E) .
XPath query returns an unexpected value from
an array . . . . . . . . . . . . . .
An activity has stopped because of an
unhandled fault (Message: CWWBE0057I) . . .
A microflow is not compensated . . . . . .
A long-running process appears to have stopped
Invoking a synchronous subprocess in another
EAR file fails . . . . . . . . . . . .
Unexpected exception during execution
(Message: CWWBA0010E) . . . . . . . .
Event unknown (Message: CWWBE0037E) . .
Cannot find nor create a process instance
(Message: CWWBA0140E) . . . . . . . .
The failed state of the process instance does not
allow the requested sendMessage action to be
performed (Message: CWWBE0126E) . . . .
Uninitialized variable or NullPointerException
in a Java snippet . . . . . . . . . . .
Standard fault exception missingReply
(message: CWWBE0071E) . . . . . . . .
Parallel paths are sequentialized . . . . . .
Copying a nested data object to another data
object destroys the reference on the source
object . . . . . . . . . . . . . . .
CScope is not available . . . . . . . . .
Working with process-related or task-related
messages . . . . . . . . . . . . . . .
Troubleshooting the administration of business
processes and human tasks . . . . . . . . .

617
619
622
623
623
623
623
624
624
625
625
626
626

626
627
627
628

628
628
629
629

ACTIVITY view . . . .
ACTIVITY_ATTRIBUTE view
ACTIVITY_SERVICE view .
APPLICATION_COMP view
ESCALATION view . . .
ESCALATION_CPROP view
ESCALATION_DESC view .
ESC_TEMPL view . . . .
ESC_TEMPL_CPROP view .
ESC_TEMPL_DESC view .
PROCESS_ATTRIBUTE view
PROCESS_INSTANCE view
PROCESS_TEMPLATE view
QUERY_PROPERTY view .
TASK view . . . . . .
TASK_CPROP view . . .
TASK_DESC view . . . .
TASK_TEMPL view . . .
TASK_TEMPL_CPROP view
TASK_TEMPL_DESC view .
WORK_ITEM view . . .

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

655
656
657
657
658
660
660
660
662
662
662
663
663
664
665
668
669
669
671
671
671

Appendix B. Business Process


Choreographer REST APIs . . . . . . 675
Task template list resource . . . . . . .
Retrieve a list of task templates . . . .
Task template resource . . . . . . . .
Retrieve a task template . . . . . . .
Task template client settings resource . . .
Retrieve client settings for a task template .
Task template client resources . . . . . .
Retrieve a list of client resources for a task
template . . . . . . . . . . . .
Task list resource . . . . . . . . . .
Retrieve a list of tasks . . . . . . .
Task resources . . . . . . . . . . .
Create a task instance . . . . . . .
Update the task properties of multiple task
instances . . . . . . . . . . . .
Task (existing instance) resources . . . . .
Retrieve task details . . . . . . . .

.
.
.
.
.
.
.

.
.
.
.
.
.
.

676
676
678
678
680
680
681

.
.
.
.
.

.
.
.
.
.

681
682
682
684
684

.
.
.

. 685
. 687
. 687

Contents

vii

Update the properties of a task .


Start a new task . . . . . .
Claim the responsibility for a task
Release a claimed task . . . .
Complete a task . . . . . .
Suspend a task . . . . . . .
Resume a suspended task . . .
Terminate a task . . . . . .
Delete a task . . . . . . .
Task input data resources . . . .
Retrieve the input data for a task .
Set the input data for a task . .
Task output data resources . . . .
Retrieve the output data for a task
Set the output data for a task . .
Task fault data resources . . . .
Retrieve the fault data for a task .
Set the fault data for a task . . .

viii

Business Process Choreographer

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

689
690
692
693
694
695
697
698
699
700
700
701
702
702
703
704
704
706

Task binary custom property resources . . . . .


Create a binary custom property for a task . .
Retrieve the value of a binary custom property
of a task . . . . . . . . . . . . . .
Set the value of a binary custom property of a
task . . . . . . . . . . . . . . .
Task binary custom property metadata resources
Retrieve metadata for a binary custom property
of a task . . . . . . . . . . . . . .
Task role resources . . . . . . . . . . .
Retrieve users or groups associated with a task
role . . . . . . . . . . . . . . . .
Transfer a task to another user or group . . .
Assign a user to a task role . . . . . . . .

707
707
708
709
711
711
712
712
714
715

Notices . . . . . . . . . . . . . . 717

Part 1. Business processes and human tasks in WebSphere


Process Server

Copyright IBM Corp. 2006, 2008

Business Process Choreographer

Chapter 1. About business processes


A business process is a set of business-related activities that are invoked to achieve
a business goal.
A process that is defined in the Web Services Business Process Execution Language
(WS-BPEL) comprises:
v The activities that are the individual steps within the process. An activity can be
one of several different types. Also, an activity can be categorized as either a
basic activity or a structured activity.
Basic activities are activities that have no structure and do not contain other
activities, for example, assign or invoke activities.
Structured activities are activities that contain other activities, for example,
sequence or while activities.
v The partner links, also known as interface partners or reference partners, that
specify the interaction with external partners using WSDL interfaces.
v The variables that store the data that is exchanged with the process and passed
between activities.
v Correlation sets that are used to correlate multiple service interactions with the
same business process instance. Correlation sets are based on application data
that is contained in messages that are exchanged with the process.
v Fault handlers that deal with exceptional situations that can occur when a
business process runs.
v Event handlers that receive and process unsolicited messages in parallel to the
normal process execution.
v Compensation handlers that specify the compensation logic for a single activity,
a group of activities, or a scope.
For more information on these constructs, refer to the BPEL specification.
Business Process Choreographer also supports the IBM extensions to the BPEL
language, such as:
v Human task activities for human interaction. These inline to-do tasks can be
steps in the business process that involve a person, for example, completing a
form, approving a document, and so on.
v Script activities for running inline Java code. The Java code can access all of the
BPEL variables, correlation properties, partner links, and process and activity
contexts.
v Information service activities to directly access WebSphere Information Server
or relational databases.
v Valid-from timestamps for process model versioning.
v Extensions for manually setting or controlling the transactional boundaries in a
business process.
v Timeouts for activities.
Related information
Business Process Execution Language for Web Services, Version 1.1
OASIS Web Services Business Process Execution Language, Version 2.0
IBM Corporation 2004, 2007

Process templates
A process template is a process definition that is deployed and installed in the
runtime environment.
Process properties are specified when the process is defined. In the runtime
environment, properties for process templates are stored in the
PROCESS_TEMPLATE database view.
In addition, an installed business process can also have one of the following states:
Started
When a process template is created and started, new instances of the
template can be started.
Stopped
The process template must be stopped before the business process
application can be uninstalled. When a process template is in the stopped
state, no new instances of this template can be created and started.

Business process types


Business processes can be either long-running or microflows.

Long-running processes
A long-running business process is interruptible, and each step of the process can
run in its own physical transaction. Long-running business processes can wait for
external stimuli. Examples of external stimuli are events that are sent by another
business process in a business-to-business interaction, responses to asynchronous
invocations, or the completion of a human task.
A long-running process has the following characteristics:
v Runs in multiple transactions.
v Interacts with services synchronously and asynchronously.
v Its state is stored in the runtime database, which makes the process
forward-recoverable

Microflows
A microflow runs in one physical thread from start to finish without interruption.
Microflows are sometimes referred to as non-interruptible business processes.
Microflows can have different transactional capabilities. A microflow participates in
the unit of work that can be either a global transaction or an activity session.
A microflow has the following characteristics:
v Runs in one transaction or activity session
v Normally runs for a short time
v Its state is transient, and it is therefore not stored in the runtime database
v It typically invokes services synchronously
v It can have only non-interruptible child processes
v It cannot contain:
Human tasks
Wait activities
Non-initiating receive activities or pick activities
Related concepts

Business Process Choreographer

Factors affecting business process interactions on page 18


A number of factors affect the behavior of business processes in the various
invocation scenarios. These include the interaction style, the type of business
process, the operation type, and the service endpoint resolution.

Process versioning
You can create new versions of your business process, so that multiple versions of
the same processes can co-exist in a runtime environment.
You can include versioning information, such as a valid-from date, when you
define the business process in WebSphere Integration Developer. The version of a
process is determined by its valid-from date. This means that different versions of
a process can have the same process name but they have different valid-from
dates. The version of a process that is used at runtime is determined by whether
the process is used in an early-binding scenario or a late-binding scenario.
Early binding
In an early-binding scenario, the decision on which version of the process
is invoked is made either during modeling or when the process is
deployed. The caller invokes a dedicated, statically-bound process. Even if
another version of the process is valid according to the valid-from dates of
the different versions, the current statically wired process is called, and all
of the other versions are ignored.
An example of early-binding is an SCA wire. If you wire a stand-alone
reference to a process component, every invocation of the process using
this reference is targeted to the specific version that is represented by the
process component.
Late binding
In a late-binding scenario, the decision on which process template is
invoked happens when the caller invokes the process. In this case, the
version of the process that is currently valid is used. The currently valid
version of a process supersedes all of the previous versions of the process.
Existing process instances continue to run with the process template with
which they were associated when they started. This leads to the following
categories of process templates:
v Currently valid process templates are used for new process instances
v Process templates that are no longer valid are still used for existing
long-running process instances
v Process templates that become valid in the future according to their
valid-from date
To apply late-binding when a subprocess is invoked, the parent process
must specify the name of the subprocess template from which the valid
subprocess is to be chosen at the reference partner. The valid-from attribute
of the process is used to determine the subprocess template that is
currently valid.
An example of late-binding is when a new process is invoked in Business
Process Choreographer Explorer. The instance that is created is always
based on the currently valid version of the process with a valid-from date
that is not in the future.
Related concepts
Late binding of processes on page 19
This scenario assumes that business processes are used as either the client or
Chapter 1. About business processes

the invoked service. It applies late binding with respect to the used process
version as determined by the validFrom process property.

Process instances
A process instance is a stateful manifestation of a process template.
Business processes defined in Web Services Business Process Execution Language
(WS-BPEL) represent stateful Web services, and as such, they can have
long-running interactions with other Web services. Whenever a BPEL process is
started, a new instance of that process is created that can communicate with other
business partners. An instance completes when its last activity completes, a
terminate activity runs, or the instance experiences a fault that is not handled by
the process.
Many process instance properties are inherited from the corresponding process
template. Others, such as the state of the process instance, are assigned and
modified during the lifetime of the process instance. All of these properties are
stored in the PROCESS_INSTANCE database view. The properties for the activities
in the process instance are stored in the ACTIVITY database view.

Process life cycle


When a process is initiated, the processing of a business process instance is started,
and it begins to interact with its environment. This means that certain interactions
are only possible in certain process states, and these interactions, in turn, influence
the state of the process instance.

State transition diagrams for process instances


Processes change state whenever something of significance happens during the life
cycle of the process instance. For example, an API request causes a process in the
running state to be put into the suspended state. State transition diagrams show
the state transitions that can occur during the process life cycle.

Conventions used in these diagrams


The state transitions in the diagrams are indicated by numbers. These numbers are
then explained in the supporting text. In addition, the diagrams contain the
following types of symbols:
Symbol

Explanation
Transient state. These states are not visible.

running
Persistent state.

running
Transient end state.

finished
Persistent end state.

finished

Business Process Choreographer

Symbol

Explanation

State transitions that are triggered


automatically by Business Flow Manager.

State transitions that are the result of an


external interaction using an API.

13

State transitions that are controlled by


Business Flow Manager, or are the result of
an external interaction using an API.

State transition diagram for microflow instances


A microflow is considered to be stateless because the process is always run in a
transaction and instance information is not persisted for navigating the process
instance. However, depending on the process definition and how Business Flow
Manager is configured, the state of a microflow can be exposed in Common Base
Events or in the audit log.
The following diagram shows the states that a microflow instance can have.
1

running

3
2
failing
finished
4

failed

After normal initiation of the process instance, the first process state a process
instance reaches is the running state (1). When a process instance runs normally
through to completion, the process state changes from running to finished (2). If a
fault reaches the process boundary, the process is put into the failing state (3). The
process stays in the failing state while the fault handler runs. After this, the process
instance is put into the failed state (4).
All of these state transitions are triggered by Business Flow Manager. After a
microflow starts, you cannot influence these automatic steps.

State transition diagram for long-running process instances


A long-running process runs in several transactions. The state of a long-running
process is persisted, and it is therefore visible. The following diagram shows the

Chapter 1. About business processes

state transitions that can occur for a long-running process instance.


1

running
2

15

11

10

terminating

16

failing

14

finished
suspended
20

17
compensating
8

compensating

20

compensation
failed
20

20

terminated

18

13
12

failed
20

The running, finished, failing, and failed states, and the state transitions between
them are the same as for microflows.
A process instance is terminated by either an external request, or a terminate
activity. The termination of a process instance can span multiple navigation steps
and therefore multiple chained transactions, for example, to terminate
long-running activities or subprocesses. During this termination phase, the process
instance is in the terminating state (5), (14), (18). When all of the long-running
parts of the process are terminated, the state of the process instance also changes to
terminated (6).
When a child process ends successfully and the parent process fails later, the child
process can be compensated. During compensation, the child process is in the
compensating state (7). If compensation ends successfully, the child process is put
into the compensated state (8). If compensation is not successful, the child process
is put into the compensation-failed state (9). These state transactions are initiated
by the parent process automatically.
If the navigation of the process instance is still active, that is, it is in the running,
or failing state, it can be suspended with an API request. It can then be reactivated
either after a specified time, or by a resume request. The state of the process
changes from running or failing to suspended (11), (12) with the suspend request,
and from suspended to running or failing with the resume request (10), (13). A
process in the suspended state can also be terminated (14). Only top-level process
instances can be suspended and resumed. However, the suspend or resume state is
propagated to the child processes.
When a process reaches one of the end states, finished, terminated, or failed, it can
be started again with a restart API request (15), (16), (17). Only top-level process
instances can be restarted, while only child process instances can be compensated.
A process instance can be deleted when it reaches an end state (20). The process
can be deleted automatically if the automatically delete on completion attribute is

Business Process Choreographer

set accordingly, or it can be triggered by an explicit delete request.

Life cycle management of subprocesses


A process that is started by another process is known as a subprocess. The way in
which the life cycle of subprocesses can be managed depends on how these
processes are modeled.
For modularity and reuse, it often makes sense to implement one or more steps of
the business logic as a separate process and to invoke this process from the main
process. A subprocess can also start another process. This can lead to a hierarchy of
process instances. When these processes are deployed, all of the process templates
in the process-to-process relationship must be deployed to the same Business
Process Choreographer database.
A subprocess can have a peer-to-peer relationship or a parent-child relationship
with the calling process. This relationship determines the behavior of a subprocess
when an action that manages the process life cycle is invoked for the calling
process. The life cycle operations comprise suspend, resume, terminate, delete, and
compensation. In a parent-child relationship, operations that manage the process
life cycle can be taken only on top-level process instances.
The process-subprocess relationship is determined by the autonomy attribute of the
subprocess. This attribute can have one of the following values:
Peer

A peer process is considered to be a top-level process. A top-level process is


a process instance that either is not invoked by another process instance, or
is invoked by another process instance, but it has peer autonomy. If the
subprocess is part of a peer-to-peer relationship, life cycle operations on
the calling process instance are not propagated to the subprocess instance.
A long-running process that is created and started using a one-way
interface is considered to be a peer process. Its autonomy attribute is
ignored at runtime.

Child If the subprocess is part of a parent-child relationship, life cycle operations


on the parent process instance are applied to the subprocess instance. For
example, if the parent process instance is suspended, all of the subprocess
instances with child autonomy are suspended, too. The child process must
be complete when it returns to its parent process, that is, the last operation
of a child process must be its reply to the calling parent process. Make sure
that all of the possible paths in the process logic end with a reply activity
as the last operation in the path.
A microflow always runs as a child process, that is, its autonomy attribute
is ignored.
A parent-child relationship can be established only between processes that
interact directly. If another SCA component intercepts this interaction, it
might prevent a parent-child relationship from being established, for
example, an interface map component that is wired between the two
process components.

State transition diagram for activities


The state of an activity instance changes when a significant step in the execution of
the activity instance occurs. The states and the state transitions depend on the type
of activity.

Chapter 1. About business processes

States and state transitions are important in the life cycle of basic activities. Basic
activities are grouped into the following activity types. The state transitions
diagrams vary according to the activity type:
v Short-lived activities, such as assign, empty, reply, rethrow, throw, terminate, and
Java snippet activities
v Activities that wait for an external event, such as receive and wait activities
v Pick (receive choice) activities
v Invoke activities
v Human task activities
In contrast to the state diagrams for process instances, activity end states are not
explicitly exposed. The life cycle of an activity depends on the enclosing process.
Activities are always deleted with the process instance.

Conventions used in these diagrams


The state transitions in the diagrams are indicated by numbers. These numbers are
then explained in the supporting text. In addition, the diagrams contain the
following types of symbols:
Symbol

Explanation
Transient state. These states are not visible.

running
Persistent state.

running

State transitions that are triggered


automatically by Business Flow Manager.

State transitions that are the result of a user


interaction, for example, by an API request.

13

State transitions that are controlled by


Business Flow Manager or by a user
interaction.

State transition diagram for short-lived activity types


The following state diagram shows the states and the state transitions for simple,
short-lived activity types, such as: assign, empty, reply, rethrow, throw, terminate,
and Java snippet activities. It introduces the states: inactive, skipped, finished,

10

Business Process Choreographer

failed, stopped, and terminated. These states are common to all of the basic activity
11

skipped
9a

inactive
10a

10b

3a

3c

types.

stopped
13

9b

running

failed

14

9d

9c

11

terminated

3b

finished
12

After an activity is created, it is in the inactive state (1). Activities that are enclosed
in a flow can have multiple incoming links and a join condition. Before such an
activity can start, all of the incoming links must be navigated. The
suppressJoinFailure attribute of the activity and the outcome of the evaluation of
the join condition determine the subsequent behavior of the activity:
v The join condition evaluates to false and the suppressJoinFailure attribute is
set to true.
The state of the activity changes to skipped (2), and the links leaving the activity
are navigated as dead paths.
v The join condition evaluates to false and the suppressJoinFailure attribute is
set to false.
The activity remains in the inactive state because it has not been started, and a
bpws:joinFailure standard fault is raised.
v The join condition evaluates to true.
For activities that are not enclosed in a flow, this is the expected behavior. The
activity is activated, and its state changes to running (3a). The activity
implementation is run, and then the activity state changes to finished (3b). If the
continueOnError attribute is set to no and the implementation fails, for example,
when the syntax of a copy statement in an assign activity is incorrect, the state
of the activity changes to failed (3c). All short-lived activities are
non-interruptible. As a result, the running state is never visible.
An activity instance that is not activated can be skipped manually. In this case, the
activity state changes from inactive to skipped (2) as soon as the activity is
reached, regardless of the outcome of the join condition. The transition conditions
of the links that leave the activity are also evaluated. If the activity is automatically
skipped, the conditions are not evaluated.
Fault handling behavior when the continueOnError attribute is set to no
If the continueOnError attribute is set to no, a fault that is not caught by
an immediately enclosing fault handler causes the activity to be put into
the stopped state (9a - 9d). The stopped state can be reached in the
following situations:
v The activation of the activity fails, for example, if an exception occurs
during the evaluation of the join condition.
The state of the activity changes from inactive to stopped (9a). The
activity can be repaired by an administrator with the help of a
Chapter 1. About business processes

11

forceRetry API request. The state of the activity changes to inactive (10a)
and the activation of the activity is tried again. If the retry is successful,
the state changes to running (3a), and finally to finished (3b). If the retry
is not successful, the activity is put into the stopped state again (14).
You can change the continue-on-error behavior with the API repair
request. If this is done and the activation fails again, the activity ends in
the inactive state (10a), and the fault is propagated to the fault handlers
of the enclosing scope.
v The implementation of the activity fails, for example, because the XPath
expression in an assign statement causes an exception.
The state of the activity changes from running to stopped (9b). Because
the state change occurs in a single transaction, the running state is not
visible.
The activity can be repaired by an administrator with the help of a
forceRetry API request. The activity is put back into the running state
(10b). The activity can also be repaired with a forceComplete API
request. In this case, the activity is put into the finished state (11), and
the navigation of the process continues.
If the activity is repaired, the stopped state can be reached again (14) if
the implementation of the activity fails again during the repair step. If
the continue-on-error behavior is changed with the API repair request
and the implementation fails again, the activity ends in the failed state,
and the fault is propagated to the fault handlers of the enclosing scope.
v The evaluation of the transition conditions on a link leaving the activity
fails.
The state of the activity was finished or skipped before the error
occurred (9c or 9d). The activity can be repaired by an administrator
with the help of a forceComplete API request. If the evaluation is then
successful, the state is finished again (11). If the evaluation is not
successful, the state of the activity is either stopped (14) or failed (12).
If an activity is in the stopped state and the enclosing scope is terminated,
for example, because of an uncaught fault in a parallel branch, the activity
is terminated. Its state changes to the terminated state (13).

12

Business Process Choreographer

State transition diagram for activities that wait for an external


event
The following diagram shows the states and the state transitions that can occur
during the life cycle of a wait or a receive activity.
11

skipped
2

10a

inactive
6

failed

9a

terminated

20

9d

14

9b

waiting
4

10b

stopped
9c
11

finished
12

The starting phase of receive and wait activities, and the state transitions to and
from the stopped state are the same as for short-lived activities. However, after
receive and wait activities are activated, the state changes to waiting instead of
running (3). The receive or wait activity is now ready to receive an external
request, or to wait for the specified timeout, before it can complete and move to
the finished state (4). For a receive activity, the transition to the finished state is
triggered by the message that is received. For a wait activity, this transition is done
automatically after the specified wait time elapses, or it can be forced using a
force-complete API request.
The implementation of a wait or receive activity is more complex than the
implementation of simple, short-lived activity types. The wait or receive activity
might fail before the start of the activity completes, for example, when the
evaluation of the wait time of a wait activity fails. If the continueOnError attribute
is set to no, this failure causes the activity state to change to failed (6) before it can
reach the waiting state.
While the activity is in the waiting state, the enclosing process might receive a
terminate request, or a fault occurs in a branch that is parallel to the wait or
receive activity. If any of these events occur, the wait or receive activity is
terminated, and the state of the activity changes to terminated (5).
A wait or receive activity can be skipped while it is in the waiting state. The state
of the activity changes immediately to the skipped state (20). In this case, the
transition conditions of the links that leave the activity are evaluated.

Chapter 1. About business processes

13

State transition diagram for a pick (receive choice) activity


The states and state transitions for pick activities (also known as receive choice
activities) are shown in the following state diagram.
9d

skipped

1
2

10a

inactive
6

failed

9a

20
3

expired
7
10b

waiting

terminated
4

9b

14

13

stopped
9c

finished

11

12

For pick activities, the states and state transitions (1) through (6), and the
transitions to and from the stopped and skipped states are the same as for receive
activities.
In addition, a pick activity can expire when the on-alarm branch of a waiting pick
activity is activated before a request for the pick activity arrives. The activity is
then in the expired state (7).

State transition diagram for an invoke activity


The following diagram shows the states and the state transitions that can occur
during the life cycle of an invoke activity with an asynchronous implementation.
The implementation is asynchronous if the service reply happens in a subsequent
transaction to the service request transaction. The SCA qualifier of the process and
the service component determine whether a service is called synchronously or
asynchronously.

14

Business Process Choreographer

9d

skipped

10a

9a

expired

inactive
20

terminated

running

13

9
10b

stopped

failed

11

14

9c

finished
12

The activation of an invoke activity is the same as the activation of all of the other
activity types (1), (2).
When an invoke activity runs normally through to completion, the activity is
started and the state changes to running (3). If the service invocation returns
successfully, the activity is put into the finished state (4).
As long as the service has not replied or the activity is in the stopped state, an
administrator can force retry or force complete the activity. This can be useful if the
service cannot reply, for example, because of a system outage. The state transitions
from running to stopped (9), failed (8), and finished (4) can also be caused by the
corresponding API. If the asynchronous service is a child process, then the activity
cannot be force retried or force completed while it is in the running state.
As with all other activities, an invoke activity can stop (9). It can then be repaired
by administrative actions or terminated because the enclosing scope or process is
also terminated (13).
Activities in the running state can expire if expiration is defined for the activity.
The activity state is then expired (7) and a timeout fault is thrown. This fault can
be handled by a fault handler.
If the enclosing scope of the activity is terminated, for example, because of a
failure in a parallel path in the process, and the activity is in the running state, the
activity is also terminated and put into the terminated state (5).
The state transitions for invoke activities with synchronous service calls are the
same as those for Java snippets. The differences in the states and the state
transitions between synchronous and asynchronous invocations are as follows:
v The running state for invoke activities with synchronous service calls is never
visible.

Chapter 1. About business processes

15

v Expiration is not applicable for invoke activities with synchronous calls; the
expired state can never be reached.
v An invoke activity with a synchronous service call is never terminated.

State transition diagram for a human task activity


The following diagram shows the states and the state transitions that can occur
during the life cycle of a human task activity.
10a
9a

9d

skipped

1
2

inactive

20

20

expired
5

3
10b

terminated

ready

10

14

9a

12
8

12

14

claimed

15
10

13

4
11

failed
finished

stopped

9c

12

The runtime behavior of a human task activity is similar to that of an invoke


activity. The running state of an invoke activity corresponds to the ready and
claimed states of a human task activity. The ready state indicates that the activity is
available to be worked on by a person. When someone claims the activity to work
on it, the activity is put into the claimed state (15).
The person working on the activity provides the information that is required and
completes the activity. The activity is then in the finished, failed, or stopped state.
Alternatively, the person who claimed the activity might decide that it cannot be
completed. The person then releases the activity for someone else to work on. In
this case, the activity is returned to the ready state (16).
A human task activity can be skipped while it is in the ready or claimed state. In
both cases, the state changes to skipped and the inline human task is terminated.
In the following navigation step, the transition conditions of the links leaving the
activity are evaluated.

16

Business Process Choreographer

The other state transitions are the same as for invoke activities with asynchronous
service calls.
Related concepts
Fault handling and compensation handling in business processes on page 26
A fault is any exceptional condition that can change the normal processing of a
business process. A well-designed process should consider faults, and handle
them whenever possible. Compensation is one way of handling faults.

Invocation scenarios for business processes


A business process is an SCA (Service Component Architecture) component
implementation type. It can expose services to other partners and consume services
provided by other partners. A business process can be a service provider that is
made available by the Business Process Choreographer APIs, an SCA service
provider for other SCA service components, or an SCA client that invokes other
SCA service components, including other business processes.
Business processes as service providers that are made available by the Business
Process Choreographer APIs
You can use the Business Flow Manager API to instantiate business
processes. Business Process Choreographer client applications also use this
API to exploit business processes as service providers. These client
applications can create and start business process instances, and query and
manipulate existing process instances. The Business Flow Manager API is
provided as an EJB, a Web service, and a JMS message interface that you
can use to design EJB, Web service, and JMS clients.
Business processes as SCA service providers for other SCA service components
In this invocation scenario, a business process represents an SCA
component that can be invoked by other SCA components acting as clients.
As an implementation of an SCA component, services provided by a
business process can be invoked from SCA clients and other SCA
components. These mechanisms include:
v Wires for connecting an SCA client (reference) and the interface of a
component that represents a business process
v SCA qualifier settings for component references and interfaces that
determine aspects, such as interaction style, transaction behavior, and
interaction reliability
Business processes as SCA clients that invoke other SCA service components
Conversely, because a business process is an implementation of an SCA
component, services consumed by it can be provided by other SCA
components or SCA imports. A BPEL partner link used in an outbound
interaction is represented by an SCA reference. This reference can be wired
to other SCA components or imports, and SCA qualifiers can be used to
associate quality-of-service attributes with the interaction.
Business processes as SCA clients that invoke other business processes
If both the SCA client and the SCA services are represented by business
processes, you can select both of them on the SCA level and on the
business process level. On the SCA level, you can use SCA wires to connect
the SCA client to SCA services. On the business process level, you can
associate partner links with the names of the business processes that act as
service providers.

Chapter 1. About business processes

17

Factors affecting business process interactions


A number of factors affect the behavior of business processes in the various
invocation scenarios. These include the interaction style, the type of business
process, the operation type, and the service endpoint resolution.
Interaction style
Operations provided by a business process can be invoked synchronously
or asynchronously.
Important: Reasonable response times for synchronous interactions should
not exceed a few seconds. If a request-response operation that is
implemented by a business process does not return its results within a
short time period, consider using an asynchronous interaction style to
improve performance. A synchronous invocation of such operations results
in blocked resources. It is also prone to timeout situations that are
dependent on the system workload and are therefore non-deterministic.
Business process type
A business process can be a microflow or a long-running process. The
characteristics of each of the process types affect invocation scenarios.
WSDL operation type
SCA references and SCA interfaces are associated with a WSDL port type
containing one or more operations. Each operation can be a one-way or a
request-response operation. A one-way operation implies a service
execution the completion of which is not made known to the invoking
client. The service execution ends with the successful invocation of the
associated service. A request-response operation implies a service execution
the completion of which is made known to the invoking client. The service
execution ends when the result of the service execution is made available
to the invoking client.
Service endpoint resolution
In the context of business processes, an invoking client can be associated
with a service to be invoked in the following ways:
v An SCA wire statically associates an SCA reference to the interface of the
invoked service. This is an SCA-level mechanism and it can be applied if
the client side, the service side, or both are implemented as business
processes.
v An endpoint reference can be set in the context of a partner link that is
part of the business process acting as an SCA client. The endpoint
reference uniquely determines the communication endpoint of the Web
service that is to be invoked. Generally, any Web service can be invoked.
An endpoint reference can be applied to either a Web service binding or
an SCA binding.
v A business process template name can be set for a partner link that is
part of a business process acting as an SCA client. The template name
uniquely determines the name of another business process that is
deployed in the same server or cluster.
Related concepts
Business process types on page 4
Business processes can be either long-running or microflows.

18

Business Process Choreographer

Dynamic binding between business processes and SCA


services
This scenario assumes that a business process is used as a client, and the process
model allows endpoint references to be set when the process runs. Dynamic
service bindings allow business processes to invoke services, the addresses of
which are determined at runtime. This is especially useful if the service endpoint is
unknown at development time.
The services with which a business process interacts are modeled as partner links
in the process model. Before operations on a partners service can be invoked using
a partner link, the binding and communication data for the partner service must be
available. The relevant information about a partner service is usually set as part of
business process deployment. As an alternative to the static association of partner
links with services endpoints, you can establish the relationship dynamically by
assigning endpoint references to partner links. If a process definition contains
assignment activities that initialize partner links with endpoint references before
the partner link is used for outbound interactions, then the SCA reference
associated with the partner link does not need to be statically wired to another
service.
Include in your process model either an assign activity or a Java snippet activity to
which you assign the endpoint reference value of the partner link. If the client is a
microflow, the service is invoked synchronously. For a long-running process, the
service is invoked asynchronously. The preferred interaction style of the service
interface is ignored.

Late binding of processes


This scenario assumes that business processes are used as either the client or the
invoked service. It applies late binding with respect to the used process version as
determined by the validFrom process property.
The process template name of the target process service is used in the following
situations:
v In the client process, the process template name of the target process service is
set in the partner link of the process definition
v The endpoint reference of the target process service is evaluated by the
getServiceRefForProcessTemplate Java snippet API or the
getServiceRefForProcessTemplate XPath function, and assigned to the partner
link
Related concepts
Process versioning on page 5
You can create new versions of your business process, so that multiple versions
of the same processes can co-exist in a runtime environment.

Passing parameters between business processes and


services
A business process can consume service component architecture (SCA) services, or
it can be consumed by other SCA services. The way in which data is exchanged
between the SCA service and the process depends on how the process was
modeled.

Chapter 1. About business processes

19

A business process consumes a service


The consumption of a service in a business process is implemented using a
Business Process Execution Language (BPEL) invoke activity in the process model.
The data that is passed to the SCA service is retrieved from one or more BPEL
variables. Usually, the data is passed by value, which means that the invoked
service works with a copy of the data.
Under certain circumstances, data can be passed by reference. Passing data by
reference can help to improve the performance of business processes.
If all of the following conditions are met, the data is passed by reference to the
business process:
v The invocation of the service is synchronous.
v The BPEL process and the invoked service are in the same module.
v The data is exchanged using data-typed variables.
If the invoked service modifies the data, these changes are applied to the
corresponding BPEL variables. However, as a best practice the invoked service
should not update the data because any changes that are made to the data are not
persistent. For long-running processes the changes are discarded when the current
transaction commits, and for microflows the changes are discarded when the
process ends. In addition, an event is not generated when the variable is updated
by the invoked service.

A business process is consumed by a service


A business process that is consumed by other services contains receive activities,
pick activities, or event handlers in the process model. The data that is passed to
the process is written to one, or more BPEL variables. Usually, the data is passed
by value.
However, if all of the following conditions are met, the data is passed by reference:
v The invocation of the business process is synchronous.
v The service and the invoked business process are in the same module.
v The data is exchanged using data-typed variables.
If the invoked process modifies the BPEL variables, the input data from the calling
service is also modified.

Transactional behavior of business processes


Business processes are executed as part of transactions. The navigation of a
business process can span multiple transactions in the case of long-running
processes, or happen as part of one transaction in the case of microflows. Such
navigation transactions can be triggered by external requests, internal messages, or
responses from asynchronous services. When a transaction starts, the required
activities are performed according to the process definitions. Invoked services can
participate in the transaction.
Related concepts
Invocation scenarios for business processes on page 17
A business process is an SCA (Service Component Architecture) component
implementation type. It can expose services to other partners and consume
services provided by other partners. A business process can be a service

20

Business Process Choreographer

provider that is made available by the Business Process Choreographer APIs, an


SCA service provider for other SCA service components, or an SCA client that
invokes other SCA service components, including other business processes.

Transactional behavior of microflows


Microflows are short-lived processes. They can run either in a transaction, or in an
activity session as specified on the SCA component of the microflow. Microflows
that are executed as part of a transaction are explained here.
Microflows are not interruptible. Therefore, a microflow cannot contain activities
that wait for an external event, or for a user interaction, for example, human task
activities.
Microflows are transient. The process instance state of a microflow is held in
memory, and not stored in the runtime database. However, the state of a microflow
instance can be persisted in the audit log or in Common Base Events.
The following diagram shows the transaction of a microflow and the services that
the microflow interacts with. The services inside the transaction boundary
participate in the microflow transaction; those outside the boundary do not
participate in the transaction.

Process
Receive

Invoke

Reply

Invoke

Invoke

Reply
Fault

Invoked services and microflow transactions


Although a microflow runs in one transaction, the execution of a microflow can
involve more than one transaction. This is because a service that is called through
an invoke activity can either participate in the transaction of the microflow, or it
can run in its own transaction.
The following settings determine whether the service participates in the transaction
of the microflow or runs in its own transaction.
v The interaction style that is used to call the service.
The interaction style can be synchronous or asynchronous. The style is
determined by the preferred interaction style of the target SCA component or the
Chapter 1. About business processes

21

SCA import, and whether the operation is one-way operation or a


request-response operation as shown in the following table:
Table 1.
Preferred interaction style of
the target component or
import
One-way operation

Request-response operation

Any

Asynchronous invocation

Synchronous invocation

Synchronous

Synchronous invocation

Synchronous invocation

Asynchronous

Asynchronous invocation

Synchronous invocation

Note: The invocation from a microflow of a request-response operation with a


preferred interaction style of asychronous is an example of an antipattern for
service invocation. When the invoked service is a long-running process, the
microflow transaction can time out before the long-running process completes,
and a runtime error occurs.
v The Service Component Architecture (SCA) transaction qualifiers that are
specified for the process and the service that is called:
The suspendTransaction qualifier on the reference of the process component
specifies whether the transaction context of the process is propagated to the
services to be invoked.
The joinTransaction qualifier on the service interface specifies whether a
service participates in the transaction of its caller if a transaction is
propagated.
Based on these settings, the following rules apply to the invoked service:
Synchronous invocation
joinTransaction

suspendTransaction = true

suspendTransaction = false

joinTransaction = true

The service does not


participate in the microflow
transaction

The service participates in


the microflow transaction

joinTransaction = false

The service does not


participate in the microflow
transaction

The service does not


participate in the microflow
transaction

If a service participates in a microflow transaction, the changes that are


made by the service to the transactional resources are persisted only if the
microflow transaction commits. If a service does not participate in the
microflow transaction, the changes that are made by the service to the
transactional resources might be persisted even if the transaction is rolled
back. You can use compensation to undo the changes made by the service.
Asynchronous invocation
The service always runs in its own transaction. To ensure that the sending
of the asynchronous SCA message participates in the current navigation
transaction, the asychronousInvocation qualifier of the microflow must be
set to commit.
Related concepts
Compensation in business processes on page 30
Compensation is the means by which operations in a process that have
successfully completed can be undone.

22

Business Process Choreographer

Transactional behavior of long-running processes


A long-running process spans multiple transactions. Each transaction is triggered
either by a Java Messaging Service (JMS) message or by a work-manager-based
implementation.
To allow navigation across transaction boundaries, the states of the process
instance and its activity instances are persisted in the database.
The following diagram shows how each navigation step in a long-running process
is performed in its own transaction. A navigation step can span multiple activities
as shown by the invoke activity that calls a service. Also, multiple activities can be
run in one transaction.

Process

Receive

Invoke

Invoke

Invoke

Reply

Service

The following describes the transaction boundaries of a long-running process. You


can influence transaction boundaries by using the transactional behavior attribute.
However, Business Flow Manager can add or remove transaction boundaries at
any time.
In general, a transaction boundary is needed in the following situations:
v When waiting for an external request, that is, upon reaching a receive activity or
pick activity (also known as a receive choice activity) in the process navigation
for which a corresponding request has not been received yet
v When scheduling a timer for a wait activity
v When invoking a service asynchronously using an invoke activity
v When invoking a human task activity
In addition, Business Flow Manager introduces transaction boundaries in the
following situations. However, your process design must not rely on these
boundaries as they can be overridden during process navigation, or they might
change in the future.
v Upon receiving a request for a receive activity or pick activity that initiates the
process
v When a fault is raised during process navigation
v Before and after an invoke activity is started that invokes a service
synchronously, and this service does not participate in the transaction of the
process
Chapter 1. About business processes

23

v When propagating life-cycle operations to child processes, for example, when a


parent process is suspended, its child processes are suspended in subsequent
transactions
v When the process instance is to be deleted automatically upon completion of the
process
v When trying to recover from a failure that causes the rollback of a transaction
spanning a series of activities
v Where specified using the transactional behavior attribute
If you need guaranteed transaction boundaries, it is a good practice to factor out
the business logic that needs to be executed in a single transaction into a
microflow, or subprocess. The logic of a microflow is always run in a single
transaction.

Influencing transaction boundaries


When you model a business process, you can suggest transaction boundaries for
invoke, snippet, and human task activities by changing the transactional behavior
attribute of the corresponding activity. The attribute can take one of the following
values:
Commit before
The current transaction is committed, and a new transaction is started. The
activity with this attribute value becomes the first activity of the new
transaction.
Commit after
The activity participates in the current transaction. After the activity
completes successfully, the transaction is committed, and a new one is
started. A new transaction is started for each immediately following
activity, and each subsequent activity becomes the first activity of one of
these new transactions.
Participates
The activity participates in the current transaction. Additional transaction
boundaries are not set, neither before nor after the activity.
In the following situations, this setting allows the transaction to continue
with the navigation of the following activities depending on the values of
their settings of the transactional behavior attributes.
v If the invoke activity invokes the service asynchronously, the arrival of
the response message triggers a new transaction. The transaction is very
short because it commits immediately after the status of the invoke
activity is updated.
v In a sequence of human task activities, two transactions are needed for
each human task activity, one to activate the human task activity and
another to complete the human task activity. If you change the setting to
Participates, you can reduce the number of transactions to one for each
human task activity. This is because the completion of the previous
human task activity, and the activation of the following activity is
performed in the same transaction.
v To enable server-controlled page flows that use the
completeAndClaimSuccessor API.

24

Business Process Choreographer

Requires own
The activity runs in its own transaction. This means that the current
transaction is committed before the activity starts, and a new transaction
starts after this activity completes.
The transactional behavior attribute is ignored if an invoke activity calls a
synchronous service that does not participate in the current transaction. In this
case, there is always a transaction boundary before the invoke activity is started,
and after the invoke activity completes.

Concurrent navigation of parallel branches in flow activities


To achieve concurrency in the navigation of parallel branches in a flow activity, a
new transaction boundary is needed at the beginning of each branch so that each
parallel activity is processed in a separate transaction. This means that the
transactional behavior attribute of the first activity of each parallel branch must be
set to Commit before or Requires own to achieve parallelism from the beginning of
the flow.
Note: For Informix, Oracle, and Derby database systems, navigation transactions
for parallel branches in a process instance are serialized, that is they cannot be run
in parallel. This is because the locks on database entities are not as granular as
those for DB2 databases. However, services triggered asynchronously by such
parallel branches still run in parallel; it is only the process navigation that is
serialized for these database systems.

Invoked services and transactions in long-running processes


A service that is called within a long-running process using an invoke activity can
either participate in the current transaction of the long-running process, or it can
run in its own transaction.
The following settings determine whether the service participates in the transaction
of the long-running process or runs in its own transaction.
v The interaction style that is used to call the service.
The interaction style can be synchronous or asynchronous. The style is
determined by the preferred interaction style of the target SCA component or
SCA import, and whether the operation is a one-way operation or a
request-response operation as shown in the following table:
Table 2.
Preferred interaction style of
target component or import One-way operation

Request-response operation

Any

Asynchronous invocation

Asynchronous invocation

Synchronous

Synchronous invocation

Synchronous invocation

Asynchronous

Asynchronous invocation

Asynchronous invocation

v The Service Component Architecture (SCA) transaction qualifiers that are


specified for the process and the service that is called:
The suspendTransaction qualifier on the reference of the process component
specifies whether the transaction context of the process is propagated to the
services to be invoked.

Chapter 1. About business processes

25

The joinTransaction qualifier on the service interface specifies whether a


service participates in the transaction of its caller if a transaction is
propagated.
Depending on the settings of the interaction style and the SCA qualifiers, the
following rules apply to the invoked service:
Synchronous invocation
joinTransaction

suspendTransaction = true

suspendTransaction = false

joinTransaction = true

The service does not


participate in the transaction
of the long-running process

The service participates in


the transaction of the
long-running process

joinTransaction = false

The service does not


participate in the transaction
of the long-running process

The service does not


participate in the transaction
of the long-running process

If a service participates in the current transaction of the long-running


process, the changes that are made by the service to the transactional
resources are persisted only if the current transaction commits.
Asynchronous invocation
The service always runs in its own transaction. To ensure that the sending
of the asynchronous SCA message participates in the current transaction,
the asychronousInvocation qualifier of the long-running process must be
set to commit.

Recovery of a successful service invocation when a transaction


rolls back
The recovery behavior depends on whether the called service participates in the
current transaction.
An invoke activity calls a service that participates in the current transaction. The
execution of the service is complete. If an error occurs after completion of the
service and the transaction is rolled back to the state that the process was in before
the transaction started, the effect of the called service is also rolled back. When the
transaction is retried, the service is called again.
In contrast, if the called service does not participate in the current transaction and
the called service returns a response, the response is stored in a separate
transaction. If an error occurs after the response is stored, the current transaction is
rolled back and the transaction is retried. During the retry the service is not called
again, however, the stored response is restored and the navigation continues.

Fault handling and compensation handling in business processes


A fault is any exceptional condition that can change the normal processing of a
business process. A well-designed process should consider faults, and handle them
whenever possible. Compensation is one way of handling faults.
Related concepts
State transition diagram for activities on page 9
The state of an activity instance changes when a significant step in the
execution of the activity instance occurs. The states and the state transitions
depend on the type of activity.

26

Business Process Choreographer

Fault handling in business processes


When a fault occurs in a process, the navigation moves to the fault handler. Fault
handlers can be specified on invoke activities, scopes, and on the process.
A fault handler can catch a specific fault name, fault type, or both. When a fault
occurs, Business Flow Manager tries to match the fault with a fault handler. It
looks for a fault handler on the enclosing scope or on the activity where the fault
occurred. It uses the following rules to select a fault handler:
v If the fault does not have any associated fault data, Business Flow Manager uses
a fault handler with the matching fault name. Otherwise, it uses the catch-all
fault handler if one is available. A fault without any data cannot be caught by a
fault handler that has a fault variable defined.
v If the fault has associated fault data, Business Flow Manager uses a fault handler
with the matching fault name and a fault variable with a type that matches the
type of the fault data. If a fault handler is not found that matches the name and
fault data type, it uses a fault handler without a fault name and a fault variable
with a type that matches the type of the fault data. If a suitable fault handler
cannot be found, it uses the catch-all fault handler if one is available. A fault
with data cannot be caught by a fault handler that does not have a fault variable
defined.
If a fault is raised that does not match any of these fault handler definitions, the
default fault handler is started. The default fault handler is not specified explicitly.
The default fault handler runs all of the available compensation handlers for the
immediately enclosed scopes in the reverse order of completion of the
corresponding scopes, and rethrows the fault to the next level, that is, the enclosing
scope or the process. On this next level, Business Flow Manager again tries to
match the fault to the fault handlers that are available.
If neither specific fault handlers nor a catch-all fault handler anywhere in the fault
handler chain catches the fault, the fault reaches the process scope, and the process
ends in the failed state. Even if a fault handler catches the fault on the process
scope and handles it, the process still ends in the failed state.

Designing fault handlers


When you design a fault handler, consider the following options:
v Catch a fault and try to correct the problem so that the business process
continues through to normal completion.
v Catch a fault and find that it is not resolvable at this scope. In this case, you
have the following additional options:
Throw a new fault.
Rethrow the original fault so that another scope can handle it.
If this is a request-response operation, reply with a fault.
Invoke a human task to correct the issue. If the fault handler cannot resolve
the issue, you might need to roll back the process and compensate it.
For long-running processes, also consider using the continueOnError
parameter on the process to handle the fault administratively.

Raising faults in business processes


You can raise faults using throw and rethrow activities, or programmatically using
a Java snippet activity.

Chapter 1. About business processes

27

To propagate faults to the caller of the process, you use the reply activity with a
fault specification.

Raising a fault using throw and rethrow activities


A throw activity in a business process can throw any type of fault, including
standard faults, but the intended usage pattern is to throw business faults. An
exception thrown by a throw activity must be caught and handled within the
business process. If a process with a request-response interface does not handle a
fault in the process, the process ends with a bpws:missingReply standard fault. For
a client application, this fault is returned in a StandardFaultException object.
You cannot return a business or standard fault with a throw activity. You must use
a reply activity to return a business fault to the process client. A reply activity can
only return a business fault that is defined on the interface that the process
implements.
A rethrow activity can be used in a fault handler to rethrow the fault to the next
enclosing scope. This might be useful when you want to do some fault handling
on the current scope, such as triggering specific compensation handlers, and still
want to make the enclosing scopes aware of this issue. You can also use a rethrow
activity when the current fault handler cannot handle the fault, and you want the
fault to be propagated to a fault handler that is defined on one of the enclosing
scopes, or on the process.
The rethrow activity can only be used within a fault handler because existing faults
can be rethrown only from fault handlers.

Raising faults programmatically


You can raise faults programmatically in a Java snippet in a business process using
the raiseFault method. You can raise a business fault in one of the following ways:
v raiseFault(QName fault, String variableName);
v raiseFault(QName fault);
The following example creates a fault called IncompleteData in the
http://process/UpdateCustomerRecordProcess/Interface0/ namespace, and then
throws this fault from a Java snippet.
javax.xml.namespace.QName fault = new javax.xml.namespace.QName
("http://process/UpdateCustomerRecordProcess/Interface0/", "IncompleteData");
raiseFault(fault);

If the thrown fault is not one that is declared on any WSDL interface, then specify
the target namespace of the process as the namespace of the fault. You can then
use a catch activity to catch this fault in a business process.
Do not throw a ServiceBusinessException object directly, but use the raiseFault
message to do so.

Using reply activities to provide a fault to the caller


The reply activity with a fault specification propagates the specified fault to the
caller of the request-response operation. The reply activity can only return a fault
that is defined on the interface that the process implements. This is useful when
the business process cannot properly respond to the caught fault, but the process

28

Business Process Choreographer

initiator can respond to it. For example, if the caller passes an account number that
is not found by the business process, the process should reply to this service call
with an AccountNotFound fault.
A reply activity with a fault specification does not complete the process and return
to the caller immediately. The navigation of the process continues until it reaches
an end state.

Retrieving information about a fault


Your process must be able to handle system faults. You can catch system faults
using either a fault handler that is defined to catch the runtimeFailure standard
fault, or a catch-all fault handler. In some situations, you might need the
information provided with the fault.
You can use one of the following constructs to retrieve this information:
v A fault variable that stores data in the event of a standard or system fault. To
make use of typed variables to handle faults, you must manually create a
StandardFaultType complex type.
v A catch-all fault handler. The catch-all fault handler does not have an associated
variable. You can retrieve the fault data from a catch-all fault handler using the
getCurrentFaultAsException method in a Java snippet activity. You must include
this Java snippet activity in the catch-all fault handler. You can use the
getCurrentFaultAsException method to retrieve data for any type of fault, not
only system faults.
The getCurrentFaultAsException method returns the fault as an exception object
of the com.ibm.bpe.api.BpelException type. The BpelException object provides
several operations to get more information about the fault, such as the fault
name. The BpelException object wraps the exception instance. Thus, you can
access the fault message and the root exception, as the following example shows:
com.ibm.bpe.api.BpelException bpelexception =
getCurrentFaultAsException();
System.out.println("Fault Name" +
bpelexception.getFaultName())
bpelexception.printStackTrace( System.out);
Throwable rootCause = bpelexception.getRootCause()

Continue-on-error behavior of activities and business processes


This parameter is available for the business process and for some activities when
you define the process in WebSphere Integration Developer. It determines what
happens to a process if an unexpected fault is raised and a fault handler is not
defined for that fault.
You can set the continueOnError parameter explicitly for invoke, Java snippet,
custom, and human task activities. For all other activities, the continue-on-error
behavior is the same as for the process.
If an unexpected fault is detected, fault handling of the activity is started. If the
continueOnError parameter is set to Yes, then the standard fault handling is
applied. If the continueOnError parameter for the activity or the process is set to
No and the fault is not handled by a fault handler, the activity is stopped.
For stopped activities, you can use the stopReason property of the activity to
determine the cause of the fault and the actions that you can take to repair it. The
following table shows the values the stopReason property can take.

Chapter 1. About business processes

29

Value of the
stopReason property Cause
STOP_REASON_
ACTIVATION_
FAILED

Allowed actions

The evaluation of the Force retry


join condition of the
activity failed.

STOP_REASON_
The implementation
IMPLEMENTATION_ of the activity threw
FAILED
a fault

Force retry or force


complete

Comments
This value is set only
when the evaluation
of the join condition
fails.
This value is set if
the implementation
of the activity failed,
for example:
v A service called by
an invoke activity
returned a fault
that is not handled
by a fault handler
v A timeout
expression failed
when a wait
activity was
activated
v A forEach counter
or evaluation of
the condition failed

STOP_REASON_
FOLLOW_ON_
NAVIGATION_
FAILED

The evaluation of a
transition condition
of an outgoing link
failed

Force complete

This value is set in


one of the following
situations:
v In a parallel flow
(also known as a
parallel activities
activity), after an
activity completed,
the transition
conditions of the
outgoing links
were evaluated,
and one of them
produced a fault.
v In a cyclic flow, if
none of the
outgoing link
qualifies for
follow-on
navigation.

Stopped activities can be repaired with the forceRetry or forceComplete methods of


the Business Process Choreographer API, or with the corresponding actions in
Business Process Choreographer Explorer. You can also modify the activity
variables before you carry out the repair action.

Compensation in business processes


Compensation is the means by which operations in a process that have
successfully completed can be undone.

30

Business Process Choreographer

Compensation processing is a means of handling faults in a running process


instance for which compensation is defined in the process model. Compensation
reverses the effects of operations, which were committed up to when the fault
occurred, to get back to a consistent state.
You can define compensation for long-running processes and for microflows in
your process model.

Compensation for long-running processes


Compensation for long-running processes is also known as business-level
compensation. This type of compensation can be defined on the scope or process
level. This means that either part of the process, or the entire process can be
compensated.
Compensation is triggered by fault handlers or the compensation handler of a
scope or a process; compensation is another navigation path of the process.
A long-running process automatically compensates child processes that have
successfully completed when the enclosing parent scope is compensated. Within a
process, only invoke and scope activities that complete successfully are
compensated.

Compensation for microflows


Compensation for microflows is also known as technical compensation. This type of
compensation is triggered when the transaction, or the activity session, that
contains the microflow is rolled back. Therefore, undo actions are typically
specified for activities that cannot be reversed by rolling back the transaction.
When a process instance runs, undo actions for compensable activities are
registered with the enclosing unit of work. Depending on the outcome of the
rollback or commit, compensation starts.
If the microflow is a child of a compensable, long-running process, the undo
actions of the microflow are made available to the parent process when the
microflow completes. It can, therefore, potentially participate in the compensation
of the parent process. For these types of microflows, it is a good practice to specify
undo actions for all of the activities in the process when you define your process
model.
If a fault occurs during compensation processing, the compensation action requires
manual resolution to overcome the fault. You can use Business Process
Choreographer Explorer to repair these compensation actions.
Related concepts
Transactional behavior of microflows on page 21
Microflows are short-lived processes. They can run either in a transaction, or in
an activity session as specified on the SCA component of the microflow.
Microflows that are executed as part of a transaction are explained here.
Related information
Using compensation in processes with Business Process Choreographer

Chapter 1. About business processes

31

Recovery from infrastructure failures


A long-running process spans multiple transactions. If a transaction fails because of
an infrastructure failure, Business Flow Manager provides a facility for
automatically recovering from these failures.
In a long-running process, the Business Flow Manager sends itself request
messages that trigger follow-on navigation. For each incoming request message, a
new transaction is started and the request message is passed to the Business Flow
Manager for processing. Each transaction consists of the following actions:
v Receive a request message
v Navigate according to the request
v Store the state in the database
v Send request messages that trigger follow-on transactions.
Business Flow Manager uses the following queues for coping with infrastructure
failures:
v The retention queue stores failed messages that will be automatically retried
v The hold queue stores messages that have failed more times than the retry limit,
and can indicate a more serious infrastructure failure or a damaged message that
cannot be processed
When messages are processed successfully, it is inferred that the infrastructure is
available. However, Business Flow Manager might fail to process a message in the
following situations:
Cause

Response

Unavailable
infrastructure

In normal processing mode, for a specified time, all messages are


kept available until the infrastructure is operational again. This
problem might be caused by a database failure, for example.

Damaged message

After a specified number of retries, the message is put into the hold
queue. From the hold queue, it can also be moved back to the input
queue, to retry the transaction.

If the infrastructure is unavailable, and the retention queue is full, message


processing is switched from normal processing to quiesce mode. In quiesce mode,
the message processing is slowed down until the infrastructure is available again.
When the infrastructure becomes available, message processing switches back to
normal mode.

Normal message processing


During normal processing, a message is processed as follows:
v If a message fails, it is stored in the retention queue.
v When a message is in the retention queue, the options are as follows:
When a subsequent message is processed successfully, all of the messages
from the retention queue are moved back to the input queue. For each
message, a count is maintained of how often the message is sent to the
retention queue. This count is referred to as the retention queue traversal count.
If this count exceeds the retry limit for a given message, the message is put in
the hold queue.
If the next message fails, it is also put in the retention queue. This process
continues until the threshold of maximum messages in the retention queue is

32

Business Process Choreographer

reached. When this threshold is reached, all of the messages are moved from
the retention queue to the input queue, and message processing is put into
quiesce mode.

Message processing in quiesce mode


In quiesce mode, processing a message is attempted periodically. Messages that fail
to be processed are put back in the input queue, without incrementing either the
delivery count or the retention queue traversal count. As soon as a message can be
processed successfully, message processing is switched back to normal mode.

Retry limit
The retry limit defines the maximum number of times that a message can be
transferred to the retention queue before it is put in the hold queue.
To be put in the retention queue, the processing of a message must fail three times.
For example, if the retry limit is 5, a message must go to the retention queue five
times (it must fail for 3 * 5 = 15 times), before the last retry is started. If the last
retry fails two more times, the message is put in the hold queue. This means that a
message must fail (3 * RetryLimit) + 2 times before it is put in the hold queue.
In a performance-critical application running in a reliable infrastructure, the retry
limit should be small: one or two, for example. If the retry limit is set to zero, a
repeatedly failing message is retried three times and then it goes immediately into
the hold queue.
This Business Flow Manager property is specified in the administrative console.
Click Servers Application servers server_name, or Servers Clusters
cluster_name if Business Process Choreographer is configured on a cluster. On the
Configuration tab, under Business Integration, click Business Process
Choreographer Business Flow Manager.

Retention queue message limit


The retention queue message limit defines the maximum number of messages that
can be in the retention queue. If the retention queue overflows, the system goes
into quiesce mode. To make the system enter quiesce mode as soon as a message
fails, set the value to zero. To make Business Flow Manager more tolerant of
infrastructure failures, increase the value.
This property is specified in the administrative console. Click Servers
Application servers server_name, or Servers Clusters cluster_name if
Business Process Choreographer is configured on a cluster. On the Configuration
tab, under Business Integration, click Business Process Choreographer Business
Flow Manager.

Replay Messages
The administrator can move the messages from the hold or retention queues back
to the internal queue. This can be done using the administrative console or using
administrative scripts.
Related tasks

Chapter 1. About business processes

33

Querying and replaying failed messages, using the administrative console on


page 285
This describes how to check for and replay any messages for business processes
or human tasks that could not be processed.
Querying and replaying failed messages, using administrative scripts on page
302
Use the administrative scripts to determine whether there are any failed
messages for business processes or human tasks, and, if there are, to retry
processing them.
Refreshing the failed message counts on page 286
Use the administrative console to refresh the count of failed messages for
business processes or human tasks.

Authorization and people assignment for processes


Authorization is used to assign specific privileges to particular users or particular
groups of users. It determines what actions users are allowed to take on processes
and activities.
The authorization for business processes is realized using human tasks.
Authorization roles are used to define the sets of actions that are available to
specific roles. The roles that are specified for the human task are inherited by the
associated business processes and activities. So, for example, if you model an inline
human task in a business process, the owner of the task automatically becomes the
activity owner. Each activity role matches exactly one human task role. Business
Flow Manager uses the activity roles for navigation and authorization.

Authorization roles for business processes


A role is a set of people who share the same level of authorization. Actions that
you can take on business processes depend on your authorization role. This role
can be a J2EE role or an instance-based role.
Related concepts
People resolution on page 81
People resolution retrieves user information from people directories based on a
set of parameterized query expressions, known as people assignment criteria.
Authorization roles for human tasks on page 68
Actions that you can take on human tasks depend on your authorization role.
This role can be a system-level J2EE role or an instance-based role.

J2EE roles for business processes


J2EE roles are set up when Business Process Choreographer is configured. For J2EE
role-based authorization, you must have a user registry configured and global
security enabled.
The following Java 2 Platform, Enterprise Edition (J2EE) roles are supported for
processes:
v BPESystemAdministrator. Users assigned to this role have all privileges. This
role is also referred to as the system administrator for business processes.
v BPESystemMonitor. Users assigned to this role can view the properties of all
business process objects. This role is also referred to as the system monitor for
business processes.
v JMSAPIUser. Business Flow Manager JMS API requests are run on behalf of the
user ID this role is mapped to, regardless of who the caller is.

34

Business Process Choreographer

You can use the administrative console to change the assignment of users and
groups to these roles.

Instance-based roles for business processes and activities


A set of predefined authorization roles is provided for business processes and
activities. You can assign these roles wen you model the process. The association of
users to instance-based roles is determined at runtime using people resolution.

Authorization roles for actions on processes


The people assigned to process roles are authorized to perform the following
actions:
Role

Authorized actions

Process starter

View the properties of the associated process instance, and its


input and output messages.

Process reader

View the properties of the associated process instance, and its


input and output messages. Members of this role also
automatically become the reader for activities, and the inline
to-do tasks (including the subtasks, follow-on tasks, and
escalations) that are associated with human task activities.

Process administrator

Administer process instances, intervene in a process that has


been initiated, create, delete, and transfer work items, change
the navigation of the process at runtime, for example, by
skipping activities. Members of this role also automatically
become the administrator for activities, and the inline to-do
tasks (including the subtasks, follow-on tasks, and escalations)
that are associated with human task activities.

Process activity
administrator

Repair activities in a process.

Scope reader

View the properties of the activities and variables in the scope.


Members of this role also automatically become the reader for
the properties of activities, and the inline to-do tasks (including
the subtasks, follow-on tasks, and escalations) that are
associated with human task activities in the scope.

Scope administrator

Administer the activities in the scope, including updating


variables for activities, skipping activities, and cancelling skip
requests. Members of this role also automatically become the
administrator for activities, and the inline to-do tasks (including
the subtasks, follow-on tasks, and escalations) that are
associated with human task activities in the scope.

The process starter is a role that is used by Business Flow Manager for process
navigation and the invocation of external services. If a process instance still exists
in the database, do not delete the user ID of the process starter from your user
registry so that the navigation of the process can continue.
Users are assigned to these roles using human tasks.
Role

People assignment

Process starter

The process starter can be specified by assigning an inline


human task to the initiating receive or pick (receive choice)
activity of a process.

Chapter 1. About business processes

35

Role

People assignment

Process reader

The process reader is specified by setting the reader role on the


administration task that is associated with the process. This role
is inherited by all of the activities in the process.

Process administrator

The process administrator is defined by an administration task


that is assigned to the process. This role is inherited by all of
the activities in the process.

Process activity
administrator

The process activity administrator is defined by an


administration task that is associated with the process. The
administrator role defined on this task is also used as the
process activity administrator.
Note: This administration task is different from the one that is
used to determine the process administrator.
The activity administration task that is defined on the process
level is the default administration task for activities that do not
have an administration task defined.

Scope reader

The scope reader is specified by setting the reader role on the


administration task that is associated with the scope. This role is
inherited by all of the activities in the scope.

Scope administrator

The scope administrator is defined by an administration task


that is assigned to the scope. This role is inherited by all of the
activities in the scope.

Authorization roles for actions on activities


When you model a human task and include it as a human task activity in a
business process, the owner of the task automatically becomes the activity owner.
Members of roles that are defined for a human task inherit the same role on the
corresponding human task activity. Business Flow Manager uses the activity roles
for navigation and authorization. The potential starters of an inline invocation task
are the potential starters of the associated receive or pick (receive choice) activity,
or the event handler.
The instance-based roles for activities are authorized to perform the following
actions:

36

Role

Authorized actions

Activity reader

View the properties of the associated activity instance, and its


input and output messages.

Activity editor

Actions that are authorized for the activity reader, and write
access to messages and other data associated with the activity.

Potential activity starter

Actions that are authorized for the activity reader. Members of


this role can send messages to receive or pick activities.

Potential activity owner

Actions that are authorized for the activity reader. Members of


this role can claim the activity.

Activity owner

Work on and complete an activity. Members of this role can


transfer their work items to an administrator or a potential
owner.

Activity administrator

Repair activities that are stopped due to unexpected errors, and


force complete long-running activities.

Business Process Choreographer

Default people assignments for process roles


Default people assignments are performed if you do not define people assignment
criteria for certain roles, or if people resolution fails or returns no result. The
following table shows which defaults apply.
Roles for business processes

If the role is not defined in the process


model ...

Process administrator

Process starter becomes process administrator

Process reader

No reader

In addition, if you do not define an invocation task to create and start the business
process, the default people assignment criteria, Everybody, is used for the potential
starters of the process.

Authorization for creating and starting business processes


The set of users that are allowed to create and start a process is determined by the
invocation task that is associated with the receive or pick (receive choice) activity
that is used to create and start a new process instance, and also by the
administration task that is associated with the process. The business process
inherits the roles that you assign to these tasks.
You can use human tasks in the following ways to create and start business
processes:
v Assign an inline invocation task to the initiating receive or pick (receive choice)
activity of the process
Some business processes might change sensitive business data and therefore
only authorized personnel should be authorized to create and start these
processes. For this type of business process, you can assign a human task to the
initiating receive activity of the process by specifying an inline invocation task
for the process template. The potential starters defined for the inline invocation
task become the potential starters of the process.
The process can be started either by creating and starting the invocation task
using the Human Task Manger API, or by initiating the process using the
Business Flow Manger API. Both ways result in the same authorization checks. If
an inline task is not specified, anyone can start the process.
v Assign a stand-alone invocation task to the initiating receive or pick (receive
choice) activity of the process
You can also use a stand-alone invocation task that is wired to the business
process to perform authorization checks when a process is started. However,
consider the following points if you use a stand-alone invocation task:
The authorization check is done only if the process is started by the
invocation task, that is, the check can be omitted when the process is started
using the Business Flow Manager API or an SCA client that is directly wired
to the process component.
It uses the SCA infrastructure to invoke the process while an inline task uses
an internal interface. An inline invocation task therefore performs better than
a stand-alone task.
You have no access to the process context in the people assignment criteria
definition. This means that stand-alone tasks do not support dynamic people
assignments based on the process context.
v Assign an administration task to the process.
Chapter 1. About business processes

37

The administrator role of the administration task is inherited by the process. A


process administrator can perform various actions on the process, including
creating and starting a process instance.

Authorization for interacting with a business process


A long-running process can have multiple receive activities, pick (receive choice)
activities, and event handlers. These are served by submitting a request to the
appropriate operation of the corresponding process instance. The process instance
is identified implicitly by providing a unique correlation set instance in the request
according to the correlation set defined in the process model.
A receive or pick activity can be used to create a process instance. So, interacting
with an existing process instance by submitting a request to a process is similar to
starting a new process instance.
The set of users that are authorized to submit a request to a process instance is
determined by the invocation task that is associated with the receive or pick
activity, or the event handlers, and by the administration task that is associated
with the process.
You can use human tasks in the following ways to interact with a process instance:
v Assign an inline invocation task to the receive activity, pick activity, or event
handler.
The potential starters that are defined for the inline invocation task submit a
request to the corresponding operation of the process. The invocation task is
optional. If an invocation task is not defined, everyone is authorized to submit a
request.
v You can also use a stand-alone human task to secure inbound operations of a
business process. The same rules and restrictions apply as for stand-alone
invocation tasks for process-creating operations.
v Assign an administration task to the process.
The administrator role of the administration task is inherited by the process. A
process administrator can interact with a process using its operations.
If an administration task is not specified for the process, the starter of the
process becomes the process administrator. In this case, the process starter is
allowed to submit requests to operations of the process instance.
If a process uses the same operation in different receive, pick (receive choice)
activities, or event handlers, and the receiving process instance is currently not
expecting a request, because the corresponding receive or pick (receive choice)
activity is not yet waiting or the event handler is not yet active, then the user
sending the request must be authorized to send a request to all of these activities
and event handlers, otherwise the request will be rejected.

Authorization for administering business processes


You can use administration tasks to authorize a user, or group of users, to perform
administrative actions on business processes and their associated activities

Process administration
To define which users are allowed to perform administrative actions and to read
the process data, you can specify an administration task as part of a long-running
business process. The administrator and reader roles for the administration task

38

Business Process Choreographer

determine who is the process administrator and the process reader. The process
administrator can, for example, force terminate the process instance. An
administration task is associated with every business process. If an administration
task is not modeled in WebSphere Integration Developer for the process, a default
administration task is created at runtime. This default task defines the process
starter as the process administrator, and does not assign any readers to the process.

Scope administration
You can model an administration task for the scope that defines scope readers and
scope administrators. A scope reader is allowed to view local variables. Scope
administrators are allowed to repair activity instances in the scope, and to view
and update local variables. If the scope is enclosed in another scope, the scope
reader and administration rights are inherited by the enclosing scope. Scope
readers and administrators also become readers and administrators of the activities
in the scope.

Activity administration
The administrator role for an activity administration task determines who is
allowed to administer the corresponding activity. The activity administrator can,
for example, force retry the activity. The administration task is created as soon as
administrative actions, that is, force retry or force complete, can be performed on
the activity instance. Reader and administrator roles of the process, and reader and
administrator roles of the enclosing scopes are automatically propagated to the
activities.
In addition, you can model administration tasks for activities in the following
ways:
v For each invoke or snippet activity. This administration task determines who is
allowed to administer the activity in addition to the process administrators.
v A default administration task for activities on the process level that applies to
every invoke or snippet activity that does not have an administration task
assigned to it.

Chapter 1. About business processes

39

40

Business Process Choreographer

Chapter 2. About human tasks


A human task is a component that allows people and services to interact.
Some human tasks represent to dos for people. These tasks can be initiated either
by a person or by an automated service. Human tasks can be used to implement
activities in business processes that require human interactions, such as manual
exception handling and approvals. Other human tasks can be used to invoke a
service, or to coordinate the collaboration between people. However, regardless of
how a task is initiated, a person from a group of people, to which the task is
assigned, performs the work associated with the task.
People are assigned to human tasks either statically, or by specifying criteria, such
as a role or a group, that are resolved at runtime using a people directory.
Alternatively the input data of a human task, or the data of a business process is
used to find the right people to work on a task.

Task templates
A human task template contains the definition of a deployed task model that was
created using WebSphere Integration Developer, or at runtime using the Business
Process Choreographer APIs.
The template contains properties, such as the task name and priority, and
aggregates artifacts, such as escalation templates, custom properties, and people
query templates. In addition to the properties that are specified when the task
template is modeled, an installed task template can also have one of the following
states:
Started
When a task template is started, new instances of the template can be
started.
Stopped
The task template must be stopped before the human task application can
be uninstalled. When a task template is in the stopped state, no new
instances of this template can be started.
You can model to-do or collaboration tasks at runtime by creating instances of the
com.ibm.task.api.TaskModel class. You can then use these instances to either create
a reusable task template, or directly create a run-once task instance. Modeling
human tasks at runtime is based on the Eclipse Modeling Framework (EMF).
Related tasks
Creating task templates and task instances at runtime on page 441
You usually use a modeling tool, such as WebSphere Integration Developer to
build task templates. You then install the task templates in WebSphere Process
Server and create instances from these templates, for example, using Business
Process Choreographer Explorer. However, you can also create human or
participating task instances or templates at runtime.

Kinds of human tasks


The task kind is derived from the task template kind that is assigned during
modeling.
Copyright IBM Corp. 2006, 2008

41

The kinds of human tasks are as follows:


To-do (participating) tasks
Support service-to-person interactions, which enable a person to implement
a service. For example, a to-do task can be a human task activity in a
business process.

Computer
system

User

Administration tasks
Administration tasks are used by administrators to solve technical
problems that occur in processes. Currently, you can use administration
tasks for business processes only.

Business
process

User

Invocation (originating) tasks


Support person-to-service interactions, which enable people to create and
start services. For example, a user can start a business process, or send it
an event by means of an invocation task.

User

Computer
system

Collaboration (pure human) tasks


Support person-to-person interactions, which enable a person to share
work with other people in a structured and controlled way. Collaboration
tasks do not interact directly with business processes or other services.

User

User

Versioning of human tasks


Use versioning when you want alternative instances of the same human task to
co-exist in the runtime environment.
You can include versioning information when you model the stand-alone human
task in WebSphere Integration Developer. The version of a task template is
determined by its valid-from date. This means that different versions of a task
template can have the same task template name, but they have different valid-from
dates. The version of a task template that is used at runtime is determined by
whether the task is used in an early-binding scenario or a late-binding scenario.

42

Business Process Choreographer

Early binding
In an early-binding scenario, the decision on which version of the task
template is used is made either during modeling, or when the task model
is deployed. The calling component invokes a dedicated, statically-bound
task template according to the Service Component Architecture (SCA)
wiring. Even if another version of the task template exists that is valid
according to its valid-from dates, the current statically wired task template
is used and all of the other versions are ignored.
An example of early-binding is an SCA wire. If you wire a stand-alone
reference to a human task component, every invocation of the task
template using this reference is targeted to the specific version that is
represented by the human task component.
Late binding
In a late-binding scenario, the decision on which human task template is
used is determined when the task instance is created. In this case, the
version of the task template that is currently valid is used. A newer version
of a task template supersedes all of the previous template versions.
Existing task instances continue to run with the task template with which
they were associated when they started. This leads to the following
categories of task templates:
v Currently valid task templates are used for new task instances
v Task templates that are no longer valid might still be valid for running
task instances
v Task templates that become valid in the future according to their
valid-from date
An example of late binding is when a new task is invoked in Business
Process Choreographer Explorer. The instance that is created is always
based on the most recent version of the task template with a valid-from
date that is not in the future. Follow-on tasks and subtasks are always
invoked using late binding.

Task instances
A task instance is a runtime occurrence of a task template.
Generally, a task instance inherits all of its properties from the corresponding task
template with the following exceptions:
Column name in
TASK_TEMPL view

Inherited by task
instance

Comments

VALID_FROM

No

Not needed by the task instance

CONTAINMENT_CTX_ID

No

Task instances are deleted


according to a different set of
rules than their corresponding
task templates

IS_AD_HOC

No

Not needed by the task instance:


v An adhoc task template creates
a non-adhoc task instance
v An adhoc task instance does
not have a task template

Chapter 2. About human tasks

43

Column name in
TASK_TEMPL view

Inherited by task
instance

IS_INLINE

Usually

Comments
The property is not inherited in
the following situations:
v A subtask instance cannot be
inline, even if its template is
defined as inline.
v A follow-on task instance
cannot be inline, even if its
template is defined as inline.
v A human task activity instance
is always related to an inline
task instance.

STATE

No

A task template must be in the


STATE_STARTED state to create
and start task instances. The
instances are then in the
STATE_READY state.

In addition, all of the custom properties of a task template (TASK_TEMPL_CPROP


view) are inherited by the custom property instances of a task instance
(TASK_CPROP view). The multilingual description of a task template
(TASK_TEMPL_DESC view) has a row for each locale. A task instance
(TASK_DESC view) only inherits these rows if the multilingual description for the
task template contains a replacement expression, for example %htm:input.part%. In
other words, the multilingual display name is only copied to the task instance if
the task instance description was copied from the task template description.
Related reference
TASK_TEMPL view on page 669
This predefined Business Process Choreographer database view holds data that
you can use to instantiate tasks.
TASK view on page 665
Use this predefined Business Process Choreographer database view for queries
on task objects.
TASK_TEMPL_CPROP view on page 671
Use this predefined Business Process Choreographer database
custom properties for task templates.
TASK_CPROP view on page 668
Use this predefined Business Process Choreographer database
custom properties for task objects.
TASK_TEMPL_DESC view on page 671
Use this predefined Business Process Choreographer database
multilingual descriptive data for task template objects.
TASK_DESC view on page 669
Use this predefined Business Process Choreographer database
multilingual descriptive data for task objects.

view to query

view to query

view to query

view to query

Stand-alone and inline tasks


The Service Oriented Architecture (SOA) patterns recommend the realization of
software solutions with a set of loosely coupled components. The human tasks that
follow the SOA patterns are called stand-alone tasks, while the human tasks that are
defined as part of a business process are called inline tasks.

44

Business Process Choreographer

The following table shows the task kinds that are available for stand-alone and
inline tasks:
Table 3.
Implementation

Invocation task

To-do task

Collaboration
task

Administration
task

Stand alone

Yes

Yes

Yes

No

Inline

Yes

Yes

No

Yes

Stand-alone tasks
Stand-alone tasks follow the SOA pattern and they are loosely coupled with the
components that invoke them (to-do tasks), or the components that are invoked by
them (invocation tasks). They can be wired to another component using the Service
Component Architecture (SCA) infrastructure.
They communicate with their partner components exclusively with SCA means.
That is, to-do tasks receive input messages and return output or fault messages,
and invocation tasks send input messages and receive output or fault messages.
No further information exchange or life cycle control happens.
Because stand-alone tasks are modeled separately, they can be reused. Stand-alone
tasks always emit their Common Event Infrastructure (CEI) and audit log events as
Human Task Manager events.
Stand-alone tasks are made available as SCA components in the following ways:
v To-do tasks have an interface that can be wired to a client component.
v Invocation tasks have a reference that can be wired to the service to be invoked.
v Collaboration tasks are self-contained SCA components. Although collaboration
tasks are stand-alone tasks, they have two human interfaces and therefore
cannot be wired to a service component.
Administration tasks are available neither as stand-alone tasks nor as SCA
components.
The following rules apply to stand-alone tasks that are used with a business
process:
v Their life cycle is independent from the process.

v
v
v
v

By default, to-do tasks are created by the process, and they are deleted when
the process is deleted.
Invocation tasks can create the process. However, they are not deleted when
the process is deleted so that the results of the task can be seen.
A to-do task is visible as an invoke activity in the business process.
Invocation tasks are wired to receive or pick activities (also known as receive
choice activities), or to an on-event event handler.
Task descriptions, display names, and documentation support multiple
languages in parallel.
Stand-alone tasks have no access to the process context. They cannot access
process variables, custom properties, or data from other process activities.

If a collaboration task is a top-level task, its life cycle is managed independently,


and it is either deleted manually, or automatically after a specified length of time.
Chapter 2. About human tasks

45

If a collaboration task is a subtask or a follow-on task, its life cycle is managed by


its parent or top-level task.

Inline tasks
Inline tasks are an integral part of the business process. Inline tasks can be to-do
tasks, invocation tasks, and administration tasks. Because collaboration tasks
leverage the interaction between people and do not directly interact with processes,
they cannot be inline tasks. Inline tasks are neither visible as SCA components
(cannot be wired), nor are they reusable in other processes or activities.
Inline tasks have access to the process context and process data, such as process
variables, custom properties, and activity data. This can be useful for tasks that
involve the separation of duties. Inline to-do tasks emit their CEI and audit log
events as Business Flow Manager human task activity events. Their subtasks and
follow-on tasks emit events as Human Task Manager events.
The following rules apply to inline tasks:
v To-do tasks are human task activities in the process. They share the same state,
but the human task activity does not reflect the task substates.
v Invocation tasks are associated with receive or pick (receive choice) activities, or
on-event event handlers.
v Administration tasks are attached either to the process, or to an activity in the
process.
v The life cycle is usually determined by the process.
To-do tasks and administration tasks are created by the business process, and
deleted with the process.
If invocation tasks are created and started by the business process, their life
cycle is determined by the process, and they are deleted with the process. If
they are created and started using the Human Task Manager API, their life
cycle is independent of the process, and their results can be displayed even
after the process is deleted.
v To-do and invocation task descriptions, display names, and documentation
support only one language.
v Inline tasks have no duration until expiration. However the human task activity
that corresponds to a to-do task can have an expiration defined.
v Only inline invocation tasks have a duration until deletion, but it applies only if
the task is started using the Human Task Manager API.
v The update action on inline tasks supports only a subset of task properties. Only
task properties that have no representation in the process or activity can be
updated. For more information on the update method, see the Javadoc for the
HumanTaskManager interface in the com.ibm.task.api package.
Inline tasks are used for process authorization:
v The roles reader, administrator, potential owner, owner, and editor of a to-do
task are identical to the corresponding roles of the human task activity in the
process.
v The potential starter role of an inline invocation task determines who is allowed
to invoke and send messages to the corresponding receive or pick (receive
choice) activity, or on-event event handler. Note that the potential starter and
potential instance creator roles have identical people assignments. If an inline
invocation task is not defined, everybody is authorized to start the activity or
event handler.

46

Business Process Choreographer

v The administrator and reader roles for a process administration task determine
who is the process administrator or the process reader. The process
administrator can, for example, force terminate the process instance.
v The administrator role for an activity administration task determines who is
allowed to administer the corresponding activity. The activity administrator and
the process administrator can, for example, force retry the activity.
v The process reader and process administrator authorization are inherited by
every process activity or inline human task.

The relationship of human tasks to business processes


Invocation tasks can be associated with receive or pick (receive choice) activities, or
on-event event handlers. These tasks can be both inline or stand-alone tasks. If you
are using the Business Flow Manager API, only inline invocation tasks can
influence the authorization for invoking the receive activity. By default, everybody
is allowed to send a message to receive or pick activities, or to on-event event
handlers. This includes invoking a business process in the case of initiating receive
activities.
An administration task is associated with every business process. The
administration task determines who is authorized to administer and read the
process. If an administration task is not modeled in WebSphere Integration
Developer for the process, a default ad-hoc task is created at runtime. This default
task defines the process starter as the process administrator and assigns no readers
to the process.
You can model an administration task for each invoke or snippet activity. This task
determines who is allowed to administer the activity in addition to the process
administrators. You can also model a default activity administration task that
applies to every invoke or snippet activity that has no explicit administration task
assigned to it.
Invoke activities have an administration task associated with them. For snippet
activities and synchronous invoke activities, this task is created only when the
activity is stopped after an invocation failure. The administration task is then used
to handle repair requests, such as force finish and force retry. For asynchronous
invoke activities, the administration task is always created. Thus, an administrator
can force retry or force finish the activity while the activity waits for the
asynchronous response.
Stand-alone to-do tasks can implement asynchronous invoke activities. These
activities also have an administration task associated with them. Inline to-do tasks
implement human task activities. An administration task is created for these
activities at runtime.
Related concepts
Life cycle of human tasks on page 55
Human tasks support people when they interact with Web services or business
processes. The interactions that can take place over the lifetime of a task
depend on whether the task is a to-do task, a collaboration task, a invocation
task, or an administration task. Certain interactions are possible only in certain
task states, and these interactions, in turn, influence the state of the human
task.
Instance-based roles for business processes and activities on page 35
A set of predefined authorization roles is provided for business processes and
Chapter 2. About human tasks

47

activities. You can assign these roles wen you model the process. The
association of users to instance-based roles is determined at runtime using
people resolution.

Subtasks
Subtasks support people when they need to delegate parts of their assigned work
to other people, but want to keep control over the overall result. They can also be
used to invoke supporting services to help people accomplish the tasks that they
are working on.
Subtasks can be created from stand-alone task templates that are stored in the
Business Process Choreographer database, from task templates created at runtime,
or by providing a new task model at runtime. The parent task can be a to-do task
or a collaboration task, and it must have the supportsSubtask attribute set to true.
The subtasks that are created can be either collaboration tasks or invocation tasks.
These subtasks can, in turn, have subtasks or follow-on tasks.
There are no restrictions on either the input message type or the output message
type. However, the starter of the subtask must provide an input message. When
the subtask is finished, the owner of the parent task can map the subtask output
data to the output message of the parent task.

Authorization considerations
In addition to what is specified for subtask when it is started, the subtask also
inherits the authorization roles from its parent task:
v The readers, editors, originator, and owner of the parent task become readers of
the subtask and its escalations
v Administrators of the parent task become administrators of the subtask
v Escalation receivers of the parent task become readers of the subtask

Life cycle considerations


When the first subtask is started, the parent task enters the waiting-for-subtask
substate. It remains in this substate until the last subtask reaches one of the end
states finished, failed, expired, or terminated. Some life cycle operations (state
changes) of the parent task are propagated to its subtasks. So, when the parent task
is suspended, resumed, terminated, deleted, or it expires, all of its subtasks are also
suspended, resumed, terminated, deleted, or expire. The escalated substate of
parent tasks is not propagated; subtasks are not escalated when the parent task is
escalated. Subtasks have their own escalations and their escalated substate is set
only when one of their own escalations is triggered.
Some life cycle operations on a subtask can conflict with the life cycle operations of
the parent task, and are therefore not allowed. These are mainly operations that
influence the end of the life cycle of a subtask and need coordination with the
parent. The following operations can be performed on subtasks:
v Life cycle operations that do not conflict with the parent task are always
supported. These are operations, such as claim, cancel claim, complete, creation
and start of subtasks or further follow-on tasks.
v Subtasks can expire.
v Subtasks can be suspended and resumed because work on a subtask might need
to be stopped although work on the parent task continues.

48

Business Process Choreographer

v Subtasks can be terminated.


v Subtasks can have their own escalations so that the parent task owner and the
subtask originator can better control the progress of the subtask.
v Auto-deletion settings are ignored for tasks that are started as subtasks. Subtasks
are deleted when their parent task is deleted. The deletion of individual subtasks
using the Business Process Choreographer APIs is not supported.

Example: Interaction between a parent task and a collaboration


task
The following figure shows a book publishing process with subtasks for the
human task activity.

Book
Publishing
Process

Task: Review Book


State: Claimed
Substate: Waiting for Subtask

Subtask:
Review Part 1

Subtask:
Review Part 3

Subtask:
Review Appendix

In a book publishing process, the Review Book task is claimed by Linda. She
realizes that the book is too large for her to review alone, and specialized
knowledge is required for some parts of it. She decides to deviate from the
standard publishing process, and assigns parts of her task to some of her
colleagues. She creates three additional tasks from the Review book section
template: Review Part 1, Review Part 3, and Review Appendix. She will
review part 2 of the book herself.
She includes the complete book as input to the subtasks so that her colleagues
have enough context information, but adds a note to the task description to tell her
colleagues to review only the parts of the book that are assigned to them. She
assigns the tasks to her colleagues: John to review part 1, Cindy part 3, and Mary
the appendix. Then she starts the three tasks as subtasks of her own Review
Book task. Her task that was in the claimed state is put into the
waiting-for-subtask substate until all three subtasks are complete.
Cindy, John, and Mary claim their subtasks and start reviewing their parts of the
book. In the meantime, Linda reviews part 2 of the book. When she finishes her
part of the review, she checks on the progress of her colleagues. Cindy and John
have completed their review, but Mary is still reviewing the large appendix.
Lindas task is still in the waiting-for-subtask substate. Although, Linda cannot
complete her task, she starts consolidating the review comments based on the
output of Cindy and Johns subtasks.
In the meantime, Mary completes her subtask too, and Lindas Review Book task
leaves the waiting-for-subtask substate. Now, Linda consolidates Marys review
comments with the rest of the book, and completes her task. The book publishing
Chapter 2. About human tasks

49

process continues. Because the Review Book task is an inline human task, it is
deleted with its subtasks when the business process instance is deleted.

Example: Interaction between a parent task and an invocation


task
The interaction between a parent task and an invocation task is similar to that of a
parent task and a collaboration task. The task owner creates a task from an existing
invocation task template, and starts it as a subtask of her own task. The parent
task enters the waiting-for-subtask substate and waits for the invocation subtask to
return. When all of the subtasks are complete, the parent task leaves the
waiting-for-subtask substate and it can be completed.
Related concepts
Authorization roles for human tasks on page 68
Actions that you can take on human tasks depend on your authorization role.
This role can be a system-level J2EE role or an instance-based role.
Life cycle of human tasks on page 55
Human tasks support people when they interact with Web services or business
processes. The interactions that can take place over the lifetime of a task
depend on whether the task is a to-do task, a collaboration task, a invocation
task, or an administration task. Certain interactions are possible only in certain
task states, and these interactions, in turn, influence the state of the human
task.

Follow-on tasks
Follow-on tasks support people when they want to delegate parts of their assigned
work to other people, and the control over the completion of the work.
Follow-on tasks can be created from stand-alone task templates that are stored in
the Business Process Choreographer database, from task templates created at
runtime, or by providing a new task model at runtime. A follow-on task can have
follow-on tasks of its own resulting in a chain of tasks.
Follow-on tasks can be only collaboration tasks. You can start a collaboration task
from a to-do task or a collaboration task that has the supportsFollowOnTask
attribute set to true.
The input message type of a follow-on task can be different from its predecessor
task. If the input message type of the follow-on task is the same as that of the
predecessor task, the input message content of the predecessor task is passed
automatically to the follow-on task. The message content can be overwritten when
the follow-on task is created or started.
For a chain of follow-on tasks, the output and fault message types of each of the
follow-on tasks must be identical to those of the top-level task in the chain,
because the last follow-on task in the chain returns the message to the calling
component or person (originator). The output or fault message content of the
parent task is always copied to the output or fault message of the follow-on task.
These messages can be modified in the follow-on task.

Authorization considerations
Follow-on tasks inherit the authorization roles from the predecessor task:

50

Business Process Choreographer

v The readers, editors, originator, and owner of the predecessor task become
readers of the follow-on task and its escalations
v Administrators of the predecessor task become administrators of the follow-on
task
v Escalation receivers of the predecessor task become readers of the follow-on task

Life cycle considerations


When the follow-on task is started, the predecessor task enters the forwarded state.
Follow-on tasks are children of their predecessor task so some life cycle operations
(state changes) of the predecessor task are propagated to its follow-on tasks. When
the predecessor task is suspended, resumed, escalated, terminated, deleted, or it
expires, all of its follow-on tasks are also suspended, resumed, escalated,
terminated, deleted, or expire.
Some life cycle operations on a follow-on task can conflict with the life cycle
operations of the predecessor task, and are therefore not allowed. These are mainly
operations that influence the end of the life cycle of a follow-on task and need
coordination with the predecessor task. The following operations can be performed
on follow-on tasks:
v Life cycle operations that do not conflict with the parent task are always
supported. These are operations, such as claim, cancel claim, complete, creation
and start of subtasks or follow-on tasks.
v Because the chain of follow-on tasks behaves like a single task to the calling
component or person (originator), follow-on tasks do not support a duration
until expiration, but expire when the expiration timer ends for the top-level task
in the chain.
v Follow-on tasks can be suspended and resumed because work on a follow-on
task might need to be stopped although work on the parent task continues.
v Follow-on tasks can be terminated.
v Follow-on tasks can have their own escalations so that the owner of the
predecessor task and the originator of the follow-on task can better control the
progress of the follow-on task.
v The deletion of individual follow-on tasks using the Business Process
Choreographer APIs is not supported.

Example: Follow-on tasks


The following figure shows a publishing process with a follow-on task for the
human task activity.

Article
Publishing
Process

Task: Review Article


State: Forwarded

Follow-on task:
Legal Review

In an article publishing process, the Review Article task is claimed by John. He is


empowered by the process to review and approve the legal aspects of articles as
Chapter 2. About human tasks

51

well. However, this article describes the collaboration with a competitor product,
and is thus very sensitive from a legal point-of-view. He reviews the informational
aspects of the article, and decides to pass the article on to Sarah from the legal
department for additional review. He creates a Legal Review task, with a
description that highlights his legal concerns. He includes the article as input to
the task, and then assigns it to Sarah. He then starts the new task as a follow-on
task of his own Review Article task. His task enters the forwarded state, and the
work on it ends. The process waits for the response from the invoked Review
Article task.
Sarah claims her Legal Review follow-on task and starts reviewing the legal
aspects. She makes some comments, and completes her task. The output message
of the follow-on task is passed to the business process. The article publishing
process continues with the output that it associates with the Review Article task,
but that actually comes from the Legal Review follow-on task. Because the
Review Article task is an inline human task, it is deleted with the Legal Review
task when the business process instance is deleted.

Escalations
An escalation is an alert that is raised automatically when a human task is not
actioned in the specified amount of time. For example, if tasks are not claimed or
are not completed within a defined time limit. You can specify one, or more,
escalations for a task. These escalations can be started either in parallel, or as a
chain of escalations.
You can define escalations for any task by defining either an escalation template
for the task template, or by defining them with an adhoc task at runtime.
Escalations are activated at a certain task state and escalate only if the expected
task state (surveillance state) has not yet been reached when the time limit for the
escalation expires. The time limit for the escalation timeout is specified as a string
and it is interpreted by the calendar specified for the task. You can specify multiple
escalations (or escalations chains) that have the same activation state.
You can define escalations that are activated when the task reaches the following
task states:
Ready For tasks in the ready state, you can define escalations for the following
situations:
v Escalate when the task is not claimed in time using the expected task
state of claimed.
v Escalate when the task is not completed in time using the expected task
state of ended.
Claimed
For to-do tasks or collaboration tasks in the claimed state, you can define
escalations for the following situations:
v Escalate when the task is not completed in time using the expected task
state of ended.
v Escalate when the subtasks of this task are not completed in time using
the expected task state of subtasks completed. Alternatively, you can use
the waiting-for-subtasks activation state as the expected state so that you
can track the progress of the subtask.

52

Business Process Choreographer

Waiting for subtask


In the waiting-for-subtasks substate of a to-do or collaboration task, you
can escalate the task when its subtasks are not completed in time using the
expected task state subtasks-completed.
Running
In the running state of an invocation task, you can escalate when the
invoked service does not return in time using the expected task state of
ended.
You can define repeating escalations. These escalations check the same expected
task state at every timeout, and perform the defined escalation action until the
expected task state is reached.
When an escalation is raised, the people affected by the escalation (the escalation
receivers) receive work items. Depending on the definition of the escalation, the
escalation receivers might also receive an e-mail notifying them that the task is
escalated. The list of users to be notified is defined by a people query. This query
must resolve to a set of user IDs for work item creation.
You can define the escalation to increase the priority of the escalated task using the
increasePriority property. The priority can be increased automatically either for the
first iteration only, or for every iteration of the escalation.

Escalation life cycle


An escalation goes through the following states during its life cycle:
v After creation, an escalation remains inactive until the task reaches the activation
state.
v When the task reaches the activation state for the escalation, the escalation is put
into the waiting state. The timer is started and the escalation waits until it times
out.
v When a timeout occurs, the atLeastExpectedState property of the task under
surveillance is checked. If the task has reached or passed this state, the
escalation state is put into the superfluous state. If the expected state is not yet
reached, the escalation is put into the escalated state, and the modeled escalation
action is invoked.
After an escalation is created, it cannot be modified. The escalation action can be
executed repeatedly. The repetition interval is defined by the autoRepeatDuration
property of the escalation.

Chained escalations
A chain of escalations is activated when the task reaches the start state for the first
escalation in the chain. All of the escalations in a chain must have the same
activation state. In a chain only one escalation is active at a time, except for
repeated escalations because they remain active. Escalations that are defined as a
sequence are processed sequentially: when the first escalation is raised, the next
escalation in the chain is activated, and so on.
The wait duration of a chained escalation is calculated relative to the timeout of
the previous escalation, and not to the time when the task reached the escalation
activation state. Thus, if the wait duration of the first escalation in a chain is two
hours and that of the second escalation in the chain is three hours, the first timeout
occurs two hours after the task reaches the activation state and the second timeout
Chapter 2. About human tasks

53

occurs three hours later, so, five hours after the task reached the activation state.
This behavior ensures that a later escalation in the chain does not time out before
its predecessors.

Dynamic durations for escalations


For some escalations, you might want to set the escalation period dynamically at
runtime. You can do this by specifying a replacement expression instead of the
fixed value when you define the escalation. The duration variable must be
enclosed in percentage signs (%).
The variable can be any of the following:
v A task variable, such as %htm:input.myEscalationDurationValue%
v A custom property, such as %htm:task.property.myEscalationDurationValue%
v A process variable, such as %wf:variable.myVariable\myPart\
myEscalationDurationValue%
You must make sure that the context data that you access is available when the
escalation is evaluated.
The following table shows when escalation durations are evaluated:
Context date must be set
before the task reaches the
following state:

Duration for

Is evaluated when

Escalation

The task reaches the


activation state of the
escalation

The task activation state of


the escalation

Escalation repetition

The escalation is raised

Escalated

Related concepts
People directories on page 81
People directories store user information that is used for people resolution.
Related tasks
Creating notification event handlers on page 529
Notification events are produced when human tasks are escalated. Business
Process Choreographer provides functionality for handling escalations, such as
creating escalation work items or sending e-mails. You can create notification
event handlers to customize the way in which escalations are handled.

E-mail notifications for escalations


When an escalation is raised, the people affected by the escalation receive a work
item. They can also be sent an e-mail that the task has been escalated. Certain rules
apply to the e-mail.
Each escalation can have a different e-mail. You can personalize the standard
escalation e-mail, for example, so that it conforms to your organizations standards.
To personalize the e-mail, edit the escalation details in the human task editor.
Both the e-mail subject line and body text can contain replacement expressions to
make the e-mail more relevant to the task that it refers to, for example, to include
the task name. These expressions must be set before the e-mail is sent otherwise
the recipients of the e-mail see %variable name% in their e-mails. You can use any
of the task and escalation expressions.

54

Business Process Choreographer

The following HTML snippet shows a sample e-mail that contains replacement
expressions:
<html>
<head>
</head>
<body lang="EN-US"><div>
<p>The task <b><span style="font-size:14.0pt">%htm:task.displayName%</span></b>
with id <b><span style="font-size:14.0pt">%htm:task.instanceID%</span></b>
&nbsp;has been escalated because the </p>
<p>expected state <b><span style="font-size:14.0pt">%htm:escalation.expectedTaskState%</span>
</b>
&nbsp;has not been reached in time.
</p>
<p>&nbsp;</p>
<p>The task has the following description: </p>
<p><span style="font-size:14.0pt;color:red">%htm:task.description%</span></p>
<p>&nbsp;</p>
<p><span style="font-size:14.0pt;color:green">The name of the Escalation is: %htm:escalation.displayName%
and the escalation description reads: %htm:escalation.description%</span></p>
<p>&nbsp;</p>
<p><a href="%htm:task.URLPrefix%?id=%htm:task.instanceID%">Task details</a></p>
<p><a href="%htm:escalation.URLPrefix%?id=%htm:escalation.instanceID%">Escalation details</a></p>
</div>
</body>
</html>

Life cycle of human tasks


Human tasks support people when they interact with Web services or business
processes. The interactions that can take place over the lifetime of a task depend
on whether the task is a to-do task, a collaboration task, a invocation task, or an
administration task. Certain interactions are possible only in certain task states, and
these interactions, in turn, influence the state of the human task.

To-do and collaboration tasks


To-do tasks and collaboration tasks support people when they perform work as
part of a business process (inline tasks), or implement a Web service that is
publicly available (stand-alone task). To-do tasks and collaboration tasks differ in
how they are started. To-do tasks are created automatically by a client application,
or calling component. Collaboration tasks are created and started by a person.
The following diagram shows the state transitions that can occur during the life
cycle of to-do tasks and collaboration tasks:

Chapter 2. About human tasks

55

terminate ( )

Terminated
Escalated
delete( )

terminate ( )

timeout

Expired
Escalated

Claimed
startTaskAsSubtask( )

WaitingForcomplete( ) Subtask

Ready
Inactive
escalate

[OK]
suspend( )
resume( )
terminate( )

Escalated
Suspended

delete( )

claim( )
cancelClaim( )

escalate

Escalated

Forwarded
Escalated
CompleteWith
FollowOnTask( )
complete( )

Finished
Escalated

suspend( )
resume( )

delete( )

Deleted
delete( )

Suspended

terminate( )
complete( )

Failed
Escalated

delete( )

delete( )

After the task is created, it is put into the inactive state. In this state, you can
update task properties or set custom properties, but the task cannot be claimed. To
work on a to-do task or collaboration task, it has to be started.
After the task is started, it is put into the ready state. In this state the task waits for
one of the potential owners to claim it and perform the work associated with this
task. In this state, the following exceptional events can occur:
v The task can be escalated because it is not claimed in time. It is put into the
escalated substate, and it stays in this substate for the rest of the task life cycle.
v The task can be suspended manually. It is put into the suspended substate. Most
actions on the task are blocked in this state. It can be resumed manually, or
automatically by a timer that is set with the suspend action.
v The task can expire. This state change ends the task.
v The task can be terminated manually using the terminate action. This state
change ends the task.
In the normal task flow, one of the potential owners claims the task, and becomes
the owner. The task is put into the claimed state and the owner and the editors can
work on it. When tasks are in the claimed state, task owners can take the following
actions:
v If they need support for their work, they can delegate pieces of work using
subtasks. These subtasks can be either collaboration tasks or invocation tasks.
The parent task then enters the waiting-for-subtask substate and remains in this
state until all of its subtasks reach an end state. The parent task can be
suspended while waiting for subtasks, but it cannot be completed and the claim
cannot be canceled.
v If they want to delegate completion of the work to someone else, they can create
a collaboration task and complete the task with the follow-on task. The parent
task is put into the forwarded end state.
v If they want to delegate the overall responsibility for tasks, they can transfer
owner work items to another potential owner, or an administrator.
v If they want to give up ownership of a task, they can cancel the claim of the
task. The task is put into the ready state again, and it can be claimed by one of
the potential owners.

56

Business Process Choreographer

In the claimed state, the following exceptional events can occur:


v The task can be escalated because it is not completed in time, or if it waits too
long for subtasks. It is put into the escalated substate, and it stays in this state
for the rest of the task life cycle.
v The task can be suspended manually. It is put into the suspended substate. Most
actions on the task are blocked in this state. It can be resumed manually, or
automatically by a timer that is set with the suspend action. Alternatively, when
the timer expires, the claim on the task is cancelled and it is put into the ready
state again.
v The task can expire. This is a state change that ends the task.
v The task can be terminated manually using the terminate action. This is a state
change that ends the task.
When the owner finishes work on the task, they complete it. The task is then put
into the finished state if it completes successfully, or the failed state if an error
occurs.
The failed, terminated, finished, and expired states are end states in which work
cannot be performed. If the task template specifies automatic deletion, the task is
either deleted immediately, or after the deletion timer expires. Without automatic
deletion, the task remains in its end state until it is explicitly deleted. When the
parent task is deleted, its subtasks are also deleted. Automatic deletion does not
apply if the task is in the forwarded end state. In this case, the parent task is
deleted with its follow-on task. The deletion timer starts when the follow-on task
reaches an end state.
Some additional rules apply to inline to-do tasks. Inline tasks are an integral part
of the business process and thus their life cycle is controlled by the process life
cycle:
v The task is created and started implicitly by the business process.
v The task is represented in the business process by a human task activity. Both
the task and the activity have the same state, for example, when that task is in
the ready state, the human task activity is in the ready state too. The human task
activity does not reflect the forwarded state or the task substates.
v If the inline task has subtasks, the human task activity is not aware of them, and
it waits in the claimed state until the parent task completes.
v If the inline task has follow-on tasks, the human task activity is not aware of
them, and it waits in the claimed state until the follow-on task completes.
v Inline to-do tasks have no duration until expiration and cannot be terminated
manually. Both expiration and termination are controlled by the human task
activity or the business process.
v The tasks are deleted with the business process. They cannot be deleted
manually, or have a duration until deletion.

Invocation (originating) tasks


Invocation tasks support people when they invoke Web services. The person who
creates and starts the invocation task becomes the task originator. When the task is
started, it automatically invokes the service and waits for its result. When the
service result is available, the invocation task stores it and the originator can
retrieve it as long as the task exists.

Chapter 2. About human tasks

57

The following diagram shows the state transitions that can occur during the life
cycle of invocation tasks:
Terminated
Escalated
terminate ( )

delete( )
Expired
Escalated

Running

Inactive

[OK]

escalate

delete( )
Finished
Escalated

Escalated

delete( )
Deleted
delete( )

Failed
Escalated

delete( )

After creation, the task reaches the inactive state. In this state, you can update task
properties, or set custom properties. To invoke the service, the task must be
started. It can be started by the originator or one of the potential starters.
After the task starts, it is put into the running state. In this state the task waits for
the invoked service to return. The following exceptional events can occur in this
state:
v The task can escalate if the service does not return in time. It is put into the
escalated substate, and it stays in this state for the rest of the task life cycle.
v The task can expire. This is a state change that ends the task.
v The task can be terminated manually using the terminate action. This is a state
change that ends the task.
The normal task flow is that the service returns with an output or fault message.
The task is then put into the finished state if an output message is returned, or the
failed state if a fault message is returned. In both cases, the message is available to
the task originator and starter.
The failed, terminated, finished, and expired states are end states. If the task
template specifies automatic deletion, the task is either deleted after the deletion
timer expires, or it is deleted manually. By default, invocation tasks are not
automatically deleted so that the result of the invoked service can be accessed.
Some additional rules apply to inline invocation tasks. These tasks are an integral
part of the business process, and thus the process can control their life cycle:
v If the business process is started using the Business Flow Manager API, or an
SCA client, the task for the activity that creates the process instance is created
and started implicitly by the business process. Invocation tasks can also be used
by process instances that are already running. In this case they are created by
the process and are associated with a receive or pick (receive choice) activity, or
an on-event event handler.
v The task is represented in the business process as a receive or pick (receive
choice) activity, or an on-event event handler. If an inline invocation task is
defined for an activity, it also defines the authorization for this activity.
v Inline invocation tasks have no duration until expiration and cannot be
terminated manually.

58

Business Process Choreographer

v If the task is started implicitly by the business process, it is also deleted


implicitly with the business process.
v If the task is started by the Human Task Manager API, then it is not deleted
with the process. If the task is modeled with automated deletion, it is deleted
after the deletion timer expires. It can also be deleted manually.

Administration tasks
Administration tasks support people in administering business processes and their
activities. If an administration task template is not available, a default
administration task is created at runtime whenever one is needed by the business
process.
The following diagram shows the state transitions that can occur for administration
tasks:
delete( )
Ready

Finished

Inactive
Escalated

start( )

complete( )

Escalated

delete( )

escalate

Business Flow Manager creates and starts an administration task implicitly in a


single transaction. The inactive state is therefore not visible externally, and the task
directly reaches the ready state.
The finished state is an end state. It does not, however, prohibit further
administrative actions.
Administration tasks are always inline tasks and thus their life cycle is controlled
by the business process. They are always deleted with the business process.
Related concepts
Subtasks on page 48
Subtasks support people when they need to delegate parts of their assigned
work to other people, but want to keep control over the overall result. They can
also be used to invoke supporting services to help people accomplish the tasks
that they are working on.
Stand-alone and inline tasks on page 44
The Service Oriented Architecture (SOA) patterns recommend the realization of
software solutions with a set of loosely coupled components. The human tasks
that follow the SOA patterns are called stand-alone tasks, while the human tasks
that are defined as part of a business process are called inline tasks.

Scenarios for invoking tasks


The various ways in which tasks can be invoked is described here.

Chapter 2. About human tasks

59

Invoking task components using the Human Task Manager API


Tasks can be instantiated by using the Human Task Manager API. Human Task
Manager API clients use the API to create and start task instances, and query and
manipulate task instances. For task invocation, the API provides methods to create
and start the following kinds of tasks:
v Stand-alone and inline invocation tasks
v Stand-alone to-do tasks
v Collaboration tasks
Administration tasks cannot be invoked using the API because they are invoked in
the context of a business process.
The API supports the following interaction styles for tasks:
v Synchronous invocation of the task and the associated service
This interaction style uses the callTask method. For one-way operations, the
invocation returns after triggering the execution of the task and the service
component. For request-response operations, the invocation waits until the
service and task are complete and the result of the invocation is returned.
This style of interaction can be applied to invocation tasks only.
v Asynchronous invocation of the task and the associated service
This interaction style uses the startTask method. For both one-way and
request-response operations, the invocation returns after triggering the execution
of the task and the service component. In addition, for request-response
operations, the invocation returns a result asynchronously that is stored as an
output or fault message in the context of the invocation task. The invoking API
client must retrieve the result programmatically using the API methods.
Alternatively, you can use a reply handler to ensure that the asynchronous
response is returned to the client as soon as the response becomes available.
This style of interaction can be applied to to-do, collaboration, and invocation
tasks.
The Human Task Manager API is provided as an Enterprise JavaBeans (EJB)
implementation and a Web service implementation. The API methods are similar
for all implementations, but differ in their functional scope.
For more information on these API methods, see the Javadoc for the
HumanTaskManager interface in the com.ibm.task.api package.

Invoking to-do tasks as SCA service components


A stand-alone to-do task represents an SCA service component that can be invoked
by an SCA client asynchronously. The mechanisms provided by SCA are available
for connecting SCA clients and stand-alone to-do tasks. This includes the SCA
means to define the following:
v Wires connecting an SCA client (reference) and the interface of a component
representing a to-do task
v SCA qualifier settings for component references and interfaces that control
aspects, such as interaction style, transaction behavior, and interaction reliability.
In addition, a stand-alone to-do task can be invoked by an SCA client that is
implemented as a business process. In this case, the connection must be considered
on both SCA and process levels. Viewed on the SCA level, the SCA client reference
is connecting to the interface of an SCA service. Viewed on the process level, the

60

Business Process Choreographer

partner link of an invoke activity is connected to a to-do task.

Invoking inline to-do tasks


A to-do task can be specified in the context of a human task activity in a
long-running business process. In this case, the task does not have a representation
on the SCA level, instead it is part of the SCA component representing the business
process. The task acts as a service provider to the human task activity. Whenever
the activity is reached during process navigation, the to-do task is invoked
asynchronously.

Invoking an SCA service through an invocation task


A stand-alone invocation task serves as an access component to an associated SCA
service. The association with the service is defined on the SCA level: the task
represents an SCA client that is wired to an SCA service component. The
invocation of an invocation task involves both Human Task Manager and SCA
levels. The invocation task itself is invoked by the Human Task Manager API,
either synchronously or asynchronously. The task (SCA client) then invokes the
associated SCA service component either synchronously if the task was invoked
synchronously, or asynchronously if the task was invoked asynchronously.
The modeling of the association between the task and the service is done on the
SCA level. The concepts and mechanisms provided by SCA are therefore available
for connecting stand-alone invocation tasks and SCA service components. This
includes the SCA means to define the following:
v Wires that connect an SCA client reference and the interface of a service
component
v SCA qualifier settings for component references and interfaces that control
aspects, such as interaction style, transaction behavior, and interaction reliability
In addition, a stand-alone invocation task can be connected to an SCA component
that is implemented by a business process.

Invoking a business process through an inline invocation task


An inline invocation task can be specified in the context of a receive or pick
activity, or an event handler in a business process. The task does not get a
representation on the SCA level, instead it is part of the SCA component that
represents the business process. Nonetheless, the task acts as a client to the
business process. Whenever the task is invoked by the Human Task Manager API,
the task in turn invokes the business process in the same way as it was invoked.

Administration tasks created for administering business


processes and activities
Administration tasks support people in administering business processes and their
activities. Business Flow Manager creates and starts an administration task for
every business process or activity type that allows administration. If an
administration task template was specified for the process or activity, this template
is used. If a template is not available, a default administration task is created,
whenever one is needed by the business process.
Related concepts
Factors affecting the behavior of stand-alone invocation tasks and their service
components on page 62
Chapter 2. About human tasks

61

You can use a stand-alone invocation task to run an Service Component


Architecture (SCA) service component that is associated with the SCA
component of the task. The association of the invocation task and service
component is modeled at an SCA level by wiring the reference of the task
component to the interface of the associated service component. A number of
factors affect the behavior of the invocation task and its associated service
component.
Scenario: stand-alone invocation tasks that support the asynchronous
invocations of services on page 63
This scenario considers the asynchronous invocations of tasks and services only.
It describes the Service Component Architecture (SCA) settings and the
expected transactional and fault behavior for this type of invocation.
Scenario: stand-alone invocation tasks that support asynchronous and
synchronous invocations of services on page 65
This scenario considers both the asynchronous and synchronous invocation of a
task and its associated service. It describes the Service Component Architecture
(SCA) settings and the expected transactional and fault behavior for these types
of invocation.
Related tasks
Creating API event handlers on page 527
An API event occurs when an API method manipulates a human task. Use the
API event handler plug-in service provider interface (SPI) to create plug-ins to
handle the task events sent by the API or the internal events that have
equivalent API events.

Factors affecting the behavior of stand-alone invocation tasks


and their service components
You can use a stand-alone invocation task to run an Service Component
Architecture (SCA) service component that is associated with the SCA component
of the task. The association of the invocation task and service component is
modeled at an SCA level by wiring the reference of the task component to the
interface of the associated service component. A number of factors affect the
behavior of the invocation task and its associated service component.
WSDL operation type
SCA references and SCA interfaces are associated with a WSDL port type
containing one or more operations. Each operation can be a one-way or a
request-response operation:
v A one-way operation implies a service execution the completion of
which is not made known to the invoking task. The task service
execution ends with the successful invocation of the associated service.
v A request-response operation implies a service execution the completion
of which is made known to the invoking task. The task execution ends
when the result of the service execution is made available to the
invoking task.
API invocation method
The Human Task Manager API supports the following interaction styles for
tasks:
v Synchronous invocation of the task and its associated service using the
callTask method
v Asynchronous invocation of the task and its associated service using the
startTask method

62

Business Process Choreographer

Execution duration of the service component


The value that you set for the execution duration must account for the
overhead that you expect due to other workload on your system. The
execution duration also has to be considered in relation to the transaction
time-out value set for the server that hosts Business Process
Choreographer. Compare these values before you decide to make a service
component with a request-response interface available for synchronous
invocation. In such cases, the execution time of your service component
must be below the transaction time-out value that is set for the server.
SCA qualifier settings
Only certain combinations of SCA qualifiers are allowed for the task
component reference and service component interface.
Related concepts
Scenarios for invoking tasks on page 59
The various ways in which tasks can be invoked is described here.

Scenario: stand-alone invocation tasks that support the


asynchronous invocations of services
This scenario considers the asynchronous invocations of tasks and services only. It
describes the Service Component Architecture (SCA) settings and the expected
transactional and fault behavior for this type of invocation.
This scenario is applicable to Human Task Manager API clients, for example,
Business Process Choreographer Explorer, that make use only of asynchronous
invocations. It avoids the need for assessing the execution duration of the service
associated with the task when you model the task.

Task component settings


The task component can take the following settings. If you use WebSphere
Integration Developer to define the task component, valid values for the attribute
type are generated automatically.
Qualifier type: attribute type

Value

Reference attribute: Multiplicity

1:1 (mandatory)

Reference qualifier: DeliverAsyncAt

commit (mandatory)

Implementation qualifier : Transaction


**

Reference qualifier : SuspendTransaction


***

Implementation qualifier : ActivitySession


***

global (mandatory)
Not applicable
true (mandatory)

Reference qualifier : SuspendActivitySession

false (default)

Reference qualifier: Reliability

assured (mandatory)

Reference qualifier: RequestExpiration

any

Reference qualifier: ResponseExpiration

any

Note:
v *: use global if you use transactions settings, and local if you use activity session
settings.
v

**

***

: if the transaction is set to global, only the transaction settings are used
: if the transaction is set to local, only the settings for the activity sessions are used

Chapter 2. About human tasks

63

Service component settings


The service component can take the following settings. If you use WebSphere
Integration Developer to define the task component, valid values for the attribute
type are generated automatically.
Qualifier type: attribute type

Value

Interface attribute: PreferredInteractionStyle

Ignored

Implementation qualifier : Transaction

local (default)
global

Interface qualifier**: JoinTransaction

false (default)
true

Implementation qualifier***: ActivitySession

any (default)

***

Interface qualifier : JoinActivitySession

false (default)

Note:
v *: use global if you use transactions settings, and local if you use activity session
settings.
v

**

***

: if the transaction is set to global, only the transaction settings are used
: if the transaction is set to local, only the settings for the activity sessions are used

The following list gives the valid combinations of settings for the service
Transaction and JoinTransaction qualifiers:
v The Transaction qualifier is set to local and the JoinTransaction is set to false.
With these settings, the task and service invocation run in separate transactions.
v The Transaction qualifier is set to global and the JoinTransaction is set to false.
With these settings, the task and service invocation run in separate transactions.
v The Transaction qualifier is set to global and the JoinTransaction is set to true.
With these settings, the task and service invocation run in the same transaction.

Transactional and fault behavior


In this asynchronous invocation scenario, the startTask method is used for API
invocation only. Task and service invocations occur in different transactions. The
following applies when a runtime exception occurs, which is not handled by the
service implementation. This scenario has the following transactional behavior and
exception handling.
When the SCA
runtime
exception
occurs

Behavior of tasks and services

One-way
operation

During service
invocation but
before the start
of the service
execution

The task receives an SCA runtime exception. The Human


Task Manager API method throws a
CoreOTaskServiceRuntimeExceptionReceivedException
exception. The task transaction is rolled back and the task
stays in the inactive state.

One-way
operation

During service
execution

The invocation task is not notified. The task moves to the


finished state. A failed event is generated that can be
handled by using the failed event manager.

Operation
type

64

Business Process Choreographer

When the SCA


runtime
exception
occurs

Behavior of tasks and services

Requestresponse
operation

During service
invocation but
before the start
of the service
execution

The task receives an SCA runtime exception. The Human


Task Manager API method throws a
CoreOTaskServiceRuntimeExceptionReceivedException
exception. The task transaction is rolled back and the task
stays in the inactive state.

Requestresponse
operation

During service
execution

The task is notified of the SCA runtime exception and stores


it in the task context in the database. If a reply handler is
available, it is used to notify the client. The task is put into
the failed state.

Operation
type

The operation definition can include one or more fault messages that can be
thrown by the service component during execution.
The task component is notified about a fault message as follows:
v The fault message is stored in the database in the context of the task
v The task is put into the failed state
v If the task was invoked synchronously and a reply handler was specified, the
reply handler is invoked to return the fault occurrence to the client
v If the task was invoked asynchronously, the fault message is returned to the
client as a FaultReplyException exception
Fault handling does not impact transactional behavior. The transactions are not
rolled back.
Related concepts
Scenarios for invoking tasks on page 59
The various ways in which tasks can be invoked is described here.

Scenario: stand-alone invocation tasks that support


asynchronous and synchronous invocations of services
This scenario considers both the asynchronous and synchronous invocation of a
task and its associated service. It describes the Service Component Architecture
(SCA) settings and the expected transactional and fault behavior for these types of
invocation.
In this scenario, Human Task Manager clients make use of both asynchronous and
synchronous invocations. It implies that you have assessed whether the service
execution time is lower than the expected value of the server transaction timeout.
Typically, execution durations must be well below the value of the server
transaction timeout.

Task component settings


The task component can take the following settings. If you use WebSphere
Integration Developer to define the task component, valid values for the attribute
type are generated automatically.
Qualifier type: attribute type

Value

Reference attribute: Multiplicity

1:1 (mandatory)

Chapter 2. About human tasks

65

Qualifier type: attribute type

Value

Reference qualifier: DeliverAsyncAt

commit (mandatory)

Implementation qualifier : Transaction


**

Reference qualifier : SuspendTransaction


***

Implementation qualifier : ActivitySession


***

global (mandatory)
Not applicable
true (mandatory)

Reference qualifier : SuspendActivitySession

false (default)

Reference qualifier: Reliability

assured (mandatory)

Reference qualifier: RequestExpiration

any

Reference qualifier: ResponseExpiration

any

Note:
v *: use global if you use transactions settings, and local if you use activity session
settings.
v

**

***

: if the transaction is set to global, only the transaction settings are used
: if the transaction is set to local, only the settings for the activity sessions are used

Service component settings


The service component can take the following settings. If you use WebSphere
Integration Developer to define the task component, valid values for the attribute
type are generated automatically.
Qualifier type: attribute type

Value

Interface attribute: PreferredInteractionStyle

Ignored

Implementation qualifier : Transaction

local (default)
global

Interface qualifier**: JoinTransaction

false (default)
true

Implementation qualifier***: ActivitySession

any (default)

***

Interface qualifier : JoinActivitySession

false (default)

Note:
v *: use global if you use transactions settings, and local if you use activity session
settings.
v

**

***

: if the transaction is set to global, only the transaction settings are used
: if the transaction is set to local, only the settings for the activity sessions are used

The following list gives the valid combinations of settings for the service
Transaction and JoinTransaction qualifiers:
v The Transaction qualifier is set to local and the JoinTransaction is set to false.
With these settings, the task and service invocation run in separate transactions.
v The Transaction qualifier is set to global and the JoinTransaction is set to false.
With these settings, the task and service invocation run in separate transactions.
v The Transaction qualifier is set to global and the JoinTransaction is set to true.
With these settings, the task and service invocation run in the same transaction.

Transactional and fault behavior


This scenario has the following transactional behavior and exception handling.

66

Business Process Choreographer

API
invocation
style

Operation
type

When the SCA runtime


exception occurs

callTask

One-way
operation

During service invocation


but before the start of the
service execution

The task receives an SCA runtime exception. The Human


Task Manager API method throws a
CoreOTaskServiceRuntimeExceptionReceivedException
exception. The task transaction is rolled back and the task
stays in the inactive state.

callTask

One-way
operation

During service execution

The task receives an SCA runtime exception. The Human


Task Manager API method throws a
CoreOTaskServiceRuntimeExceptionReceivedException
exception. The task transaction is rolled back and the task
stays in the inactive state.

callTask

Requestresponse
operation

During service invocation


but before the start of the
service execution

The task receives an SCA runtime exception. The Human


Task Manager API method throws a
CoreOTaskServiceRuntimeExceptionReceivedException
exception. The task transaction is rolled back and the task
stays in the inactive state.

callTask

Requestresponse
operation

During service execution

The task receives an SCA runtime exception. The Human


Task Manager API method throws a
CoreOTaskServiceRuntimeExceptionReceivedException
exception. The task transaction is rolled back and the task
stays in the inactive state.

startTask

One-way
operation

During service invocation


but before the start of the
service execution

The task receives an SCA runtime exception. The Human


Task Manager API method throws a
CoreOTaskServiceRuntimeExceptionReceivedException
exception. The task transaction is rolled back and the task
stays in the inactive state.

startTask

One-way
operation

During service execution

The invocation task is not notified. The task moves to the


finished state. A failed event is generated that can be
handled by using the failed event manager.

startTask

Requestresponse
operation

During service invocation


but before the start of the
service execution

The task receives an SCA runtime exception. The Human


Task Manager API method throws a
CoreOTaskServiceRuntimeExceptionReceivedException
exception. The task transaction is rolled back and the task
stays in the inactive state.

startTask

Requestresponse
operation

During service execution

The task is notified of the SCA runtime exception and


stores it in the task context in the database. If a reply
handler is available, it is used to notify the client. The
task moves to the failed state.

Behavior of tasks and services

The operation definition can include one or more fault messages which can be
thrown by the service component during execution.
The task component is notified about a fault message as follows:
v The fault message is stored in the database in the context of the task
v The task is put into the failed state
v If the task was invoked asynchronously and a reply handler was specified, the
reply handler is invoked to return the fault occurrence to the client
v If the task was invoked synchronously, the fault message is returned to the client
as a FaultReplyException exception
Fault handling does not impact transactional behavior. The transactions are not
rolled back.
Chapter 2. About human tasks

67

Related concepts
Scenarios for invoking tasks on page 59
The various ways in which tasks can be invoked is described here.

Authorization and people assignment


Authorization is the mechanism by which certain people are enabled to perform
selected actions on task templates, task instances, and escalations. Authorization
roles are used to define sets of actions available to specific roles. People can be
assigned to system-level roles using J2EE mechanisms, or to task instance roles
using people assignment criteria.

Authorization roles for human tasks


Actions that you can take on human tasks depend on your authorization role. This
role can be a system-level J2EE role or an instance-based role.
System-level Java 2 Platform, Enterprise Edition (J2EE) roles are set up when
Human Task Manager is configured. The authority level implied by these roles is
valid for all tasks and escalations. Instance-based roles are valid for individual task
and escalation instances, or the templates that are used to create task or escalation
instances. Role-based authorization requires that administration and application
security is enabled for the application server.

J2EE roles
The following J2EE roles are supported:
v TaskSystemAdministrator. Users assigned to this role have all privileges. This
role is also referred to as the system administrator for human tasks.
v TaskSystemMonitor. Users assigned to this role can view the properties of all of
the task objects. This role is also referred to as the system monitor for human
tasks.
You can use the administrative console to change the assignment of users and
groups to these roles.

Instance-based roles
A task instance or an escalation instance is not assigned directly to a person,
instead it is associated with predefined roles to which people are assigned. Anyone
that is assigned to an instance-based role can perform the actions for that role. The
association of users to instance-based roles is determined either by people
assignment, or as the result of task actions.
People are assigned to the following roles at runtime by people assignment based
on the user and user group information that is stored in a people directory:
potential creator, potential starter, potential owner, reader, editor, administrator,
and escalation receiver. The following roles are associated with only one user and
are assigned as the result of a task action: originator, starter, owner.

68

Business Process Choreographer

These roles are authorized to perform the following actions:


Role

Authorized actions

Potential creator

Members of this role can create an instance of the task. If a


potential instance creator is not defined for the task template,
then all users are considered to be a member of this role.

Originator

The person with this role has administrative rights until the task
starts. When the task starts, the originator has the authority of a
reader and can perform some administrative actions, such as
suspending and resuming tasks, and transferring work items.

Potential starter

Members of this role can start an existing task instance. If a


potential starter is not specified, the originator becomes the
potential starter. For inline tasks without a potential starter, the
default is everybody.

Starter

The person with this role has the authority of a reader and can
perform some administrative actions, such as transferring work
items.

Potential owner

Members of this role can claim a task. If a potential owner is


not defined for the task template, then all users are considered
to be a member of this role. If staff resolution fails for this role,
then the administrators are assigned as the potential owners.

Owner

The person with this role works on and completes a task.

Reader

Members of this role can view the properties of all of the task
objects, but cannot work on them.

Editor

Members of this role can work with the content of a task, but
cannot claim or complete it.

Administrator

Members of this role can administer tasks, task templates, and


escalations.

Escalation receiver

Members of this role have the authority of a reader for the


escalation and the escalated task.

Related concepts
Authorization roles for business processes on page 34
A role is a set of people who share the same level of authorization. Actions that
you can take on business processes depend on your authorization role. This
role can be a J2EE role or an instance-based role.
Subtasks on page 48
Subtasks support people when they need to delegate parts of their assigned
work to other people, but want to keep control over the overall result. They can
also be used to invoke supporting services to help people accomplish the tasks
that they are working on.
Default people assignments and inheritance rules on page 88
Default people assignments are performed if you do not define people
assignment criteria for certain task roles, or if people resolution fails or does not
return a result. The default assignments differ for inline tasks and stand-alone
tasks.

Instance-based authorization roles for task kinds


Instance-based authorization roles are associated with human tasks and escalations
when the task is modeled. The task kind determines whether a specific
authorization role is available.

Chapter 2. About human tasks

69

Role

To-do
tasks

Invocation
tasks

Collaboration Administration Comments


tasks
tasks

Potential instance X
creator

People who are allowed to create task


instances

Originator

The person who created the task

Potential owner

People who can claim and work with


tasks

Owner

The person who claimed the task

Potential starter

Starter

X
X

People who are allowed to start the


task
The person who started the task
X

Administrator

Editor

Reader

X2

People who are allowed to see task


data

Escalation
receiver

X3

X3

X3

X3

People who receive an escalation

People who are allowed to administer


a task
People who are allowed to edit task
data

Notes:
1. This role also has authorization for administrative actions on the administered process or activity
2. This role also has authorization for read operations on the administered process or activity
3. This role is authorized to perform actions on the escalations generated from these task types but not on the tasks
themselves

Authorization and work items


Every task role enables users to carry out an exact set of actions on the associated
task. A persons authorization is managed using work items. A work item
represents the relationship of the assigned person to the task actions implied by
the task role.
A work item has the following aspects:
v The identity of a user or user group
v The identity of the task upon which actions can be performed
v The task role that the users are associated with
The people associated with a work item can be specified in one of the following
ways:
v As exactly one user ID. This leads to a user work item.
v As exactly one user group ID. This leads to a group work item.
v For every user by using the Everybody people assignment criteria. This leads to
an Everybody work item.
The authorization mechanisms of Business Process Choreographer ensure that a
user can perform the actions associated with a work item if one of the following
conditions holds:
v The user logs in with a user ID that matches the specified user ID for the user
work item

70

Business Process Choreographer

v The logged-on user is a member of the group that corresponds to the specified
group ID for the group work item
v The work item is a work item that is assigned to everybody
The Human Task Manager API provides methods for querying human tasks,
escalations, and other objects. When a query is run, a users authorization to see
the queried data is ensured by returning only the data for which the user has a
work item. You can also use the API to manage instance-based authorization. This
is done by creating and deleting work items, and by transferring work items
between people. For more information on these API methods, see the Javadoc for
the HumanTaskManager interface in the com.ibm.task.api package.

People assignment criteria


People assignment criteria are constructs that are used in the task model to identify
sets of people that can be assigned to an instance-based authorization role. At
runtime, the people resolution uses the people assignment criteria to retrieve the
user IDs and other user information, for example, for composing e-mails. People
assignment criteria are also used during runtime when task models or are created
programmatically.
You can use people assignment criteria definitions (previously known as staff
verbs) in WebSphere Integration Developer to model people assignments for task
roles. A definition comprises a query name and a set of query parameters. When
the task is deployed, the assignment criteria are transformed into queries that are
specific to the people directory, for example, virtual member manager. When the
task runs, these queries retrieve the set of people who are assigned to a role, such
as potential owner.
The following example illustrates the steps that are involved in implementing a
people assignment criteria definition for a task role:
1. In WebSphere Integration Developer, a modeler associates a new task with the
people directory configuration, for example, for virtual member manager,
bpe/staff/samplevmmconfiguration.
This step determines which people assignment criteria are available for people
assignment.
2. In WebSphere Integration Developer, the modeler associates a task role with a
people assignment criteria definition.
For example, the potential owner role is associated with the people assignment
criteria Group Members, including the parameters:
v GroupName set to the value cn=group1, dc=mycomp, dc=com
v IncludeSubgroups set to the value true
3. When the task is deployed, the people assignment service establishes which
people directory provider to use. It transforms the people assignment criteria
into a query for the people directory provider, which is stored internally.
Depending on the people directory that is used, different subsets of the predefined
people assignment criteria are available when the task is modeled:
v The LDAP and virtual member manager people directory providers support all
of the predefined definitions
v The user registry people directory provider supports only those definitions that
are based on user and group names. Support is not provided for definitions
based on manager, or e-mail attributes.

Chapter 2. About human tasks

71

v The system people directory provider is for testing purposes only. Support is
limited to specifying a set of hard-coded user IDs so that access to a people
directory is not required.

Predefined people assignment criteria


Predefined people assignment criteria are provided for retrieving sets of users from
people directories.
You can use people assignment criteria (previously known as staff verbs) in
WebSphere Integration Developer to specify people assignments in a human task.
These criteria are transformed during modeling and deployment into a set of
queries that can be run on a people directory. The parameters for the following
predefined people assignment criteria are listed here:
v Department Members
v Everybody
v Group
v Group Members
v Group Members without Named Users
v Group Members without Filtered Users
v Group Search
v Manager of Employee
v Manager of Employee by user ID
v Native Query
v Nobody
v Person Search
v Role Members
v User Records by user ID
v User Records by user ID without Named Users
v Users
v Users by user ID
v Users by user ID without Named Users
Consider the following when you assign people assignment criteria:
v If you are working with large groups of people, the Group people assignment
criteria works best because it handles the members of a group as a unit. This
allows you to transfer a human task from one group to another group easily. A
persons group membership is resolved when the person logs in and accesses a
human task.
v To individually assign people that belong to a group to a human task, the Group
Members people assignment criteria provides an alternative to the group
assignment. The Group Members people assignment criteria creates an
assignment for each person individually. This assignment can then be transferred
to another person. Substitution can occur, that is, a person that is absent can be
replaced by another person. A variant of this people assignment criteria, Group
Members without Named Users supports the separation-of-duties assignment
pattern.
Note: Assigning people to a group individually can affect performance at
runtime, especially when assigning more than a few people to the group.
v To assign a few people to a human task that do not all belong to the same
group, consider using the User Records by user ID people assignment criteria
definition. You can also use this definition when the people assignment is not
statically defined during modeling, but includes replacement expressions.
Replacement expressions can refer to custom properties or the input message of
a human task. The Users by user ID people assignment criteria definition is

72

Business Process Choreographer

similar to the User Records by user ID definition. Although the Users by user ID
definition performs better than the User Records by user ID definition at
runtime, it provides less functionality:
It does not check if the user IDs are entered correctly
It does not retrieve, for example, the e-mail addresses for the user IDs
specified, which makes it less suitable for assigning people to e-mail
escalations
v The Everybody people assignment criteria definition is also worth considering. It
indicates that all authenticated users are assigned to the human task. While there
are cases where all people in an organization can do a certain job, this definition
is particularly useful during development, or when rapidly prototyping an
application.

Department Members
Use this criteria to retrieve the members of a department. It is supported by the
Lightweight Directory Access Protocol (LDAP), and the virtual member manager
people directory providers.
Parameter

Use

Type

Description

DepartmentName

Mandatory

string

Department name of the users to retrieve.


The department name must correspond to
one of the following values:
v For virtual member manager, a unique
name of a virtual member manager group
v For LDAP, a distinguished name (DN) of
an LDAP group

IncludeNestedDepartments

Mandatory

boolean

Specifies whether nested departments are


considered in the query.

AlternativeDepartmentName1

Optional

string

An additional department to which the


users can belong.

AlternativeDepartmentName2

Optional

string

An additional department to which the


users can belong.

Everybody
Use this criteria to assign every user that is authenticated by WebSphere Process
Server to a task role. This criteria has no parameters.
This criteria is supported by all of the people directory providers.

Group
Use this criteria to assign a group to a task role. This assignment creates a group
work item instead of creating user work items for every assigned user.
This criteria is supported by all of the people directory providers.

Chapter 2. About human tasks

73

Parameter

Use

Type

Description

GroupId

Mandatory

string

Group name of the users to retrieve. This


parameter supports replacement
expressions. The group ID must correspond
to one of the following values:
v For virtual member manager, a unique
name of a group entry
v For LDAP, a DN of a group entry
v For the user registry provider, the name
format you use depends on which user
repository is set for the application server
where the task is deployed:
For the local operating system, use a
group name that is supported by the
local operating system
For a stand-alone custom registry, use
a group name supported by the
custom implementation
For a stand-alone LDAP registry, use a
DN of a group entry

Group Members
Use this criteria to retrieve the members of a group. It is supported by the LDAP,
virtual member manager, and the user registry people directory providers.
Parameter

Use

Type

Description

GroupName

Mandatory

string

Group name of the users to retrieve. This


parameter supports replacement
expressions. The group ID must correspond
to one of the following values:
v For virtual member manager, a unique
name of a group entry
v For LDAP, a DN of a group entry
v For the user registry provider, the name
format you use depends on which user
repository is set for the application server
where the task is deployed:
For the local operating system, use a
group name that is supported by the
local operating system
For a stand-alone custom registry, use
a group name supported by the
custom implementation
For a stand-alone LDAP registry, use a
DN of a group entry

IncludeSubgroups

Mandatory

boolean

Specifies whether nested subgroups are


considered in the query.

AlternativeGroupName1

Optional

string

An additional group to which the users can


belong.

AlternativeGroupName2

Optional

string

An additional group to which the users can


belong.

74

Business Process Choreographer

Group Members without Named Users


Use this criteria to retrieve all of the members of a group, except for the explicitly
named users. It is supported by the LDAP, virtual member manager, and the user
registry people directory providers.
Parameter

Use

Type

Description

GroupName

Mandatory

string

Group name of the users to retrieve. This


parameter supports replacement expressions.
The group ID must correspond to one of the
following values:
v For virtual member manager, a unique
name of a group entry
v For LDAP, a DN of a group entry
v For the user registry provider, the name
format you use depends on which user
repository is set for the application server
where the task is deployed:
For the local operating system, use a
group name that is supported by the
local operating system
For a stand-alone custom registry, use a
group name supported by the custom
implementation
For a stand-alone LDAP registry, use a
DN of a group entry

IncludeSubgroups

Mandatory

boolean

Specifies whether nested subgroups are


considered in the query.

NamedUsers

Mandatory

string

The user IDs of the users to exclude from the


retrieved group members list. This parameter
supports replacement expression.

Group Members without Filtered Users


Use this criteria to retrieve all of the members of a group except for a set of users
that is defined by a search filter. It is supported by the LDAP, and virtual member
manager people directory providers.
Parameter

Use

Type

Description

GroupName

Mandatory

string

Group name of the users to retrieve. This


parameter supports replacement expressions.
The group ID must correspond to one of the
following values:
v For virtual member manager, a unique
name of a group entry
v For LDAP, a DN of a group entry

IncludeSubgroups

Mandatory

boolean

Specifies whether nested subgroups are


considered in the query.

FilterAttribute

Mandatory

string

Name of the attribute to use in the search


filter.

FilterValue

Mandatory

string

Filter value to use in the search filter. You can


use the wildcard character, asterisk (*), in the
filter.

Chapter 2. About human tasks

75

Group Search
Use this criteria to search for a group based on attribute matches, and to assign the
members of the group. It is supported by the LDAP, and virtual member manager
people directory providers.
Parameter

Use

Type

Description

GroupID

Optional

string

The group ID of the users to retrieve.

Type

Optional

string

The group type of the users to retrieve.

IndustryType

Optional

string

The industry type of the group to which the


users belong.

BusinessType

Optional

string

The business type of the group to which the


users belong.

GeographicLocation

Optional

string

An indication of where the users are located.

Affiliates

Optional

string

The affiliates of the users.

DisplayName

Optional

string

The display name of the group.

Secretary

Optional

string

The secretary of the users.

Assistant

Optional

string

The assistant of the users.

Manager

Optional

string

The manager of the users.

BusinessCategory

Optional

string

The business category of the group to which


the users belong.

ParentCompany

Optional

string

The parent company of the users.

For virtual member manager, the Group entity has properties that are equivalent to
the following Group Search criteria parameters:
v GS_GroupID: cn
v GS_DisplayName: displayName
v GS_BusinessCategory: businessCategory

Manager of Employee
Use this criteria to retrieve the manager of a person using the persons name. It is
supported by the LDAP and virtual member manager people directory providers.
Parameter

Use

Type

Description

EmployeeName

Mandatory

string

The name of the employee whose manager


is retrieved. The employee name must
correspond to one of the following values:
v For virtual member manager, the unique
name of a person entry
v For LDAP, a DN of a person entry

Manager of Employee by user ID


Use this criteria to retrieve the manager of a person using the persons user ID. It
is supported by the LDAP and virtual member manager people directory
providers.

76

Business Process Choreographer

Parameter

Use

Type

Description

EmployeeUserID

Mandatory

string

The login user ID of the employee whose


manager is retrieved. This parameter supports
replacement expressions.

Native Query
Use this criteria to define a native query based on directory-specific parameters. It
is supported by the LDAP and virtual member manager people directory
providers.
Parameter

Use

Type

Description

QueryTemplate

Mandatory

string

The query template to use. This must be one of


the following values: search, user, and
usersOfGroup.

Query

Mandatory

string

Specifies the query. This parameter supports


replacement expressions. The type of query
depends on the query template.
v search template: search filter
For virtual member manager, a valid search
expression
For LDAP, a valid LDAP filter
v user template: user DN
For virtual member manager, a unique name
of a user entry
For LDAP, a DN of a user entry
v usersOfGroup: group DN
For virtual member manager, a unique name
of a group
For LDAP, a DN of a group

AdditionalParameter1

Optional

string

Specifies the query. This parameter supports


replacement expressions. The type of parameter
depends on the query template.
v search template. Used to specify whether
recursive search is done. Supported values: yes
and no
v user template. Not supported
v usersOfGroup. Used to specify whether
recursive search is done. Supported values: yes
and no

AdditionalParameter2

Optional

string

Use this criteria to specify a base entry for


searching.
v For virtual member manager, a unique name of
a base entry, for example, dc=mycomp, dc=com
v For LDAP, a DN of a base entry

AdditionalParameter3

Optional

string

Use this criteria to specify an additional


parameter.
If you use the default mapping XSLT files, this
parameter is not supported.

AdditionalParameter4

Optional

string

Use this criteria to specify an additional


parameter.
If you use the default mapping XSLT files, this
parameter is not supported.

Chapter 2. About human tasks

77

Parameter

Use

Type

Description

AdditionalParameter5

Optional

string

Use this criteria to specify an additional


parameter.
If you use the default mapping XSLT files, this
parameter is not supported.

Nobody
Use this criteria to deny users access to a task role. Only authorization inheritance
and people resolution defaults apply with this criteria. This criteria has no
parameters.

Person Search
Use this criteria to search for people based on attribute matches. It is supported by
the LDAP, virtual member manager, and the user registry people directory
providers.
Parameter

Use

Type

Description

UserID

Optional

string

The user ID of the users to retrieve.

Profile

Optional

string

The profile of the users to retrieve.

LastName

Optional

string

The last name of the users to retrieve.

FirstName

Optional

string

The first name of the users to retrieve.

MiddleName

Optional

string

The middle name of the users to retrieve.

Email

Optional

string

The e-mail address of the users.

Company

Optional

string

The company to which the users belong.

DisplayName

Optional

string

The display name of the users.

Secretary

Optional

string

The secretary of the users.

Assistant

Optional

string

The assistant of the users.

Manager

Optional

string

The manager of the users.

Department

Optional

string

The department to which the users belong.

Phone

Optional

string

The telephone number of the users.

Fax

Optional

string

The fax number of the users.

Gender

Optional

string

Whether the user is male or female.

Timezone

Optional

string

The time zone in which the users are located.

PreferredLanguage

Optional

string

The preferred language of the user.

For virtual member manager, the PersonAccount entity has properties that are
equivalent to the following People Search criteria parameters:
v PS_UserID: uid
v PS_LastName: sn
v PS_FirstName: givenName
v PS_MiddleName: initials
v PS_Email: mail
v PS_DisplayName: displayName
v PS_Secretary: secretary

78

Business Process Choreographer

v
v
v
v

PS_Manager: manager
PS_Department: departmentNumber
PS_Phone: telephoneNumber
PS_PreferredLanguage: preferredLanguage

Role Members
Use this criteria to retrieve the users associated with a role. It is supported by the
LDAP and virtual member manager people directory providers.
Parameter

Use

Type

Description

RoleName

Mandatory

string

Role name of the users to retrieve.

IncludeNestedRoles

Mandatory

boolean

Specifies whether nested roles are considered in


the query.

AlternativeRoleName1

Optional

string

An additional role name for the user.

AlternativeRoleName2

Optional

string

An additional role name for the user.

User Records by User ID


Use this criteria to define a query for a user whose user ID is known. It is
supported by the LDAP, virtual member manager people directory providers. This
criteria returns the user IDs, the e-mail information, and the preferred locale, if set,
for these users.
Parameter

Use

Type

Description

UserID

Mandatory

string

The user ID of the user to retrieve. This


parameter supports replacement expressions.

AlternativeID1

Optional

string

An additional user ID. Use this parameter to


retrieve more than one user.

AlternativeID2

Optional

string

An additional user ID. Use this parameter to


retrieve more than one user.

Users Records by User ID without Named Users


Use this criteria to define a query for users whose user ID is known, while
excluding an explicitly named user ID. It is supported by the LDAP, virtual
member manager, and user registry people directory providers. This criteria
returns the user IDs and the e-mail information for these users.
Parameter

Use

Type

Description

UserID

Mandatory

string

The user ID of the user to retrieve. This


parameter supports replacement expressions.

AlternativeID1

Optional

string

An additional user ID. Use this parameter to


retrieve more than one user.

AlternativeID2

Optional

string

An additional user ID. Use this parameter to


retrieve more than one user.

NamedUsers

Mandatory

string

The user IDs of the users to exclude from the


user ID list. This parameter supports
replacement expressions.

Chapter 2. About human tasks

79

Users
Use this criteria to define a query for a user who is known by name. It is
supported by all of the people directory providers.
Parameter

Use

Type

Description

Name

Mandatory

string

The name of the user to retrieve.


v For virtual member manager, the unique name
of a person entry
v For LDAP, a DN of a person entry
v For the user registry provider, the name
format you use depends on which user
repository is set for the application server
where the task is deployed:
For the local operating system, use the user
ID of the user to assign
For a stand-alone custom registry, use a
person name supported by the custom
implementation
For a stand-alone LDAP registry, use a DN
of a person entry

AlternativeName1

Optional

string

An additional user name. Use this parameter to


retrieve more than one user.

AlternativeName2

Optional

string

An additional user name. Use this parameter to


retrieve more than one user.

Users by User ID
Use this criteria to define a query for a user whose user ID is known. Use short
names to specify values, for example, wpsadmin. This criteria does not require
access to a people directory. It is supported by all of the people directory
providers.
Parameter

Use

Type

Description

UserID

Mandatory

string

The user ID of the user to retrieve. This


parameter supports replacement expressions.

AlternativeID1

Optional

string

An additional user ID. Use this parameter to


retrieve more than one user.

AlternativeID2

Optional

string

An additional user ID. Use this parameter to


retrieve more than one user.

Users by User ID without Named Users


Use this criteria to define a query for users whose user ID is known, while
excluding an explicitly named user ID. Use short names to specify values, for
example, wpsadmin. This criteria does not require access to a people repository. It
is supported by all of the people directory providers.
Parameter

Use

Type

Description

UserID

Mandatory

string

The user ID of the user to retrieve. This


parameter supports replacement expressions.

80

Business Process Choreographer

Parameter

Use

Type

Description

AlternativeID1

Optional

string

An additional user ID. Use this parameter to


retrieve more than one user.

AlternativeID2

Optional

string

An additional user ID. Use this parameter to


retrieve more than one user.

NamedUsers

Mandatory

string

The user IDs of the users to exclude from the


user ID list. This parameter supports
replacement expressions.

Related concepts
Replacement expressions in people assignment criteria definitions
You can use replacement expressions as parameter values in some people
assignment criteria definitions. The people resolution can resolve the
assignment criteria at runtime, based on information supplied by the contexts.

Replacement expressions in people assignment criteria


definitions
You can use replacement expressions as parameter values in some people
assignment criteria definitions. The people resolution can resolve the assignment
criteria at runtime, based on information supplied by the contexts.
For example, the following people assignment criteria definition specifies the
htm:input.\name replacement expression as a parameter:
<verb>
<name>Users by user ID</name>
<parameter id="UserID">%htm:input.\name%</parameter>
</verb>

This variable denotes the name element of the task input message value that is
received by the task when it is initiated. People resolution dynamically replaces the
expression with the actual task input message value.
Related information
Predefined people assignment criteria on page 72
Predefined people assignment criteria are provided for retrieving sets of users
from people directories.

People resolution
People resolution retrieves user information from people directories based on a set
of parameterized query expressions, known as people assignment criteria.
Related concepts
Authorization roles for business processes on page 34
A role is a set of people who share the same level of authorization. Actions that
you can take on business processes depend on your authorization role. This
role can be a J2EE role or an instance-based role.

People directories
People directories store user information that is used for people resolution.
To support people resolution, the people directory must support the following
attributes:
v The name that identifies a user profile and the login ID of a user

Chapter 2. About human tasks

81

v To exploit information that is related to the manager of a user, the people


directory should offer a corresponding attribute, by default the manager
attribute
v To exploit the e-mail notification feature for escalations, the people directory
should offer user e-mail addresses
Business Process Choreographer supports the following people directories for
people resolution. If you want to exploit the full set of features offered by Business
Process Choreographer for people assignment, use virtual member manager as the
people directory.
v Federated repositories (also referred to as virtual member manager)
This is the default people directory that is supported by WebSphere Application
Server. It provides access to a variety of directory types, including Lightweight
Directory Access Protocol (LDAP) directories, database and file-based
repositories, and custom repositories. It also supports the federation of the
repositories.
Both person and group information can be retrieved. The supported person
schema (PersonAccount entity type) includes properties for the name, login
identity, manager identity, and e-mail address of a user. To be available for
people resolution, federated repositories must be configured as the active
security realm definition in WebSphere Application Server.
v An LDAP directory
Business Process Choreographer can directly access an LDAP directory for
people resolution without using WebSphere Application Server security. To
ensure consistency across people resolution (implemented by Business Process
Choreographer) and user authentication (implemented by WebSphere
Application Server security), WebSphere Application Server security must be
configured to access the same LDAP directory server as the one specified for
people resolution in Business Process Choreographer.
Depending on the LDAP person schema that you use, the person-related
information includes the user name, identity, manager name, and e-mail address.
To be available for people resolution, a Business Process Choreographer people
directory provider configuration is required.
v WebSphere Application Server user registry
The user registry is a subsystem of the application server for retrieving user
information. Business Process Choreographer can use this user registry as a
people directory. Business Process Choreographer uses its own user registry
people directory provider to access the WebSphere Application Server user
registry.
Related concepts
Escalations on page 52
An escalation is an alert that is raised automatically when a human task is not
actioned in the specified amount of time. For example, if tasks are not claimed
or are not completed within a defined time limit. You can specify one, or more,
escalations for a task. These escalations can be started either in parallel, or as a
chain of escalations.

People directory providers and configurations


Business Process Choreographer uses people directory providers as adapters for
accessing people directories. You can configure virtual member manager, LDAP,
the user registry, and the system people directory providers to retrieve user
information.

82

Business Process Choreographer

The decision on which people directory provider to use depends on the support
that you need from people resolution. To exploit all of the people assignment
features offered by Business Process Choreographer, use virtual member manager.
All people directory providers are made available at the node level.
Virtual member manager people directory provider
The virtual member manager people directory provider is used to access
WebSphere Application Server federated repositories. You can use this
provider to exploit the following aspects of people resolution:
v Federated repository features, including the use of various repositories,
such as file and database repositories, LDAP directories, the property
extension repository, and the federation of repositories
v E-mail notification for escalations
v Substitution for absentees
v All of the predefined people assignment criteria
Lightweight Directory Access Protocol (LDAP) people directory provider
The LDAP people directory provider is used to access an LDAP directory
directly without using WebSphere Application Server. In most cases, the
WebSphere Application Server security realm is set to Stand-alone LDAP
registry, and configured to point to the same LDAP directory as the one
referenced by the LDAP people directory provider. You can use this
provider to exploit the following aspects of people resolution:
v E-mail notification for escalations
v All of the predefined people assignment criteria
User registry people directory provider
You can use the user registry people directory provider to access the
following people directories with WebSphere Application Server: the local
operating system, a stand-alone LDAP registry, or a stand-alone custom
registry. The people directory that is used depends on the configuration of
the application server security realm. You can use this provider to exploit
the following aspects of people resolution:
v Minimum configuration of the people directory provider for Business
Process Choreographer because the repository is determined by the
security realm for the application server
v A limited set of predefined people assignment criteria. The user registry
people directory provider can resolve users and groups, but not
employee to manager relationships, user properties, or e-mail addresses.
System people directory provider
The system people directory provider has limited people resolution
support. Because the system provider supports only hard-coded queries, it
is suitable only for test purposes.
All of the people directory configurations require that WebSphere Application
Server administrative and application security are enabled.
Each of the people directory providers can be associated with one or more people
directory provider configurations. All of the configurations, except the LDAP
people directory provider, are ready to use. For the virtual member manager
people directory provider, the federated repositories functionality must be
configured in WebSphere Application Server. For the LDAP provider configuration,
the required connection parameters must be set. In addition, the transformation file
for the LDAP provider configuration must be customized.
Chapter 2. About human tasks

83

Each of the configurations is uniquely identified by its Java Naming Directory


(JNDI) name. The JNDI names are the link between a task template definition and
the people directory configuration that is to be used for resolving the people
assignments to task roles. Use WebSphere Integration Developer to specify the
configuration name for a task template. If you are defining tasks at runtime using
the task creation API, you can specify the configuration name directly in the API.
Different task templates can reference different people directory configurations.
After a task template is deployed, the people directory configuration name is fixed
for the lifetime of the deployed template. If you need to change the people
directory that is associated with the template, use WebSphere Integration
Developer to change the JNDI name of the people directory configuration that is
defined for the task template definition, and deploy the template again.
Related tasks
Configuring the LDAP people directory provider on page 194
Use this task to configure the Lightweight Directory Access Protocol (LDAP)
people directory provider for Business Process Choreographer to perform
people assignment, which determines who can start a process or claim an
activity or a task.
Configuring the Virtual Member Manager people directory provider on page
192
Configure the Virtual Member Manager (VMM) people directory provider for
Business Process Choreographer to perform people assignment, which
determines who can start a process or claim an activity or a task. The default
people directory provider is ready to use, and only needs to be configured if
you introduce custom people assignment criteria.

Mapping people assignment criteria to people queries


When an application is deployed, people assignment criteria definitions are
transformed into sets of queries that are specific to a people directory
configuration. The resulting people queries are stored with the task template in the
Business Process Choreographer database.
If you use virtual member manager as the people directory, you need to change
the predefined mappings in the transformation XSL file only if you define custom
people assignment criteria.
A transformation (XSLT) file contains the instructions for translating the people
assignment criteria. Each people directory configuration is associated with a
transformation file. The following transformation files are provided for the default
people directory configurations:
v LDAPTransformation.xsl for the LDAP people directory provider
v VMMTransformation.xsl for the virtual member manager people directory
provider
v UserRegistryTransformation.xsl for the user registry people directory provider
v SystemTransformation.xsl and EverybodyTransformation.xsl for the system
people directory provider
On Windows platforms, these files are in the install_root\
ProcessChoreographer\Staff directory. On Linux, UNIX, and i5/OS platforms,
these files are in the install_root/ProcessChoreographer/Staff directory.

84

Business Process Choreographer

People queries for a specific people directory provider


An XSL transformation file that is associated with a people directory configuration
is used to generate people queries that are specific to a particular repository. Each
query can be executed by the respective people directory provider to obtain a list
of user IDs. The predefined queries that are available to a people directory
provider correspond to the calls that can be executed by the provider, and are
therefore fixed.
The set of repository-specific queries provided by a people directory provider
correspond to the methods it can use to retrieve user information from the
corresponding people directory. You can uses this set queries to form more
complex queries as shown in the following examples:
v Combine query results so that the user IDs returned by the individual queries
are added to the current result list of user IDs. For example, the LDAP people
directory provider allows the following predefined queries:
The list of user IDs for the group members of a specified group:
<sldap:usersOfGroup groupDN="cn=group1,dc=mycomp" recursive="yes">
...
</sldap:usersOfGroup>

The distinguished name (DN) of the specified user:


<sldap:user dn="uid=user1,dc=mycomp" .../>

A complex query can be constructed for a list of user IDs for the members of
a specified group, and the DN of a specified user:
<sldap:staffQueries>
<sldap:usersOfGroup groupDN="cn=group1,dc=mycomp" recursive="yes">
...
</sldap:usersOfGroup>
<sldap:user dn="uid=user1,dc=mycomp" .../>
</sldap:staffQueries>

v Remove query results from the current result list. For example, the following
snippet shows how to remove user1 from the list of IDs retrieved for the
specified group members:
<sldap:staffQueries>
<sldap:usersOfGroup groupDN="cn=group1,dc=mycomp" recursive="yes">
...
</sldap:usersOfGroup>
<sldap:remove value="user1"/>
</sldap:staffQueries>

v Use the query results obtained from one query to influence the behavior of a
subsequent query. For example, in the following snippet, two queries are
performed. First, the value of the manager attribute in the LDAP entry for the
user uid=user1,... is retrieved and saved in an intermediate variable
supervisor. This variable is then used to look up the managers LDAP entry
and retrieve the associated user ID.
<sldap:staffQueries>
<sldap:intermediateResult name="supervisor">
<sldap:user dn="uid=user1,dc=mycomp" attribute="manager" ... />
</sldap:intermediateResult>
<sldap:user dn="%supervisor% .../>
</sldap:staffQueries>

People queries that are constructed according to these combination rules can be
executed by the people directory providers.

Chapter 2. About human tasks

85

Customizing the transformation of people assignment criteria


You might need to customize the transformation of the people assignment criteria
in the following situations: to adapt the transformation to the LDAP person and
group schemas, or to define custom people assignment criteria.
To make use of a customized transformation, you must create a transformation file.
Do not change the default transformation files and do not reuse the names of these
files for your transformation files. For new transformation files for the LDAP or
virtual member manager people directory providers, always include the User
Records by User ID people assignment criteria definition in the file. This definition
is required by Business Process Choreographer even if it is not explicitly specified
for the people assignment.
To use the new transformation file, define a new people directory configuration
that points to the file.
Related tasks
Configuring the LDAP people directory provider on page 194
Use this task to configure the Lightweight Directory Access Protocol (LDAP)
people directory provider for Business Process Choreographer to perform
people assignment, which determines who can start a process or claim an
activity or a task.
Configuring the Virtual Member Manager people directory provider on page
192
Configure the Virtual Member Manager (VMM) people directory provider for
Business Process Choreographer to perform people assignment, which
determines who can start a process or claim an activity or a task. The default
people directory provider is ready to use, and only needs to be configured if
you introduce custom people assignment criteria.
Defining custom people assignment criteria:
You might need to extend the set of predefined people assignment criteria with
criteria of your own.
When you create a custom people assignment criteria, you need to include it in the
following files:
v In the VerbSet.xml file
v In the transformation file
To make use of a customized transformation, you must create a transformation file.
Do not change the default transformation files and do not reuse the names of these
files for your transformation files.
For example, you created a new criteria Mentor of Employee. This criteria is
similar to the Manager of Employee criteria, but it retrieves the user ID of the
employees mentor instead of the employees manager.
1. In WebSphere Integration Developer, modify the VerbSet.xml file.
a. Import the VerbSet.xml file into your workspace.
The VerbSet.xml file is contained in the
com.ibm.wbit.tel.ui_6.1.version_number.jar file. You can find this file in the
shared_resources/plugins directory. If you find more than one version of the
archive file, use the file with the highest version number.
b. Edit the imported VerbSet.xml file to include the following XML snippet:

86

Business Process Choreographer

<vs:DefineVerb name=Mentor of Employee>


<vs:Description>Assigns the mentor of an employee.
Supported by sample XSLT files for:
- LDAP
</vs:Description>
<vs:Mandatory>
<vs:Parameter>
<vs:Name>EmployeeName</vs:Name>
<vs:Type>xsd:string</vs:Type>
</vs:Parameter>
</vs:Mandatory>
<vs:Optional>
<vs:Parameter>
<vs:Name>Domain</vs:Name>
<vs:Type>xsd:string</vs:Type>
</vs:Parameter>
</vs:Optional>
</vs:DefineVerb>

c. Enable human task modules to use the new verbs.


Right-click the module that is to use the new verbs, and select Properties,
then Human Task. On the Properties page, ensure that you clear the check
box for using the default verb set file.
2. In the transformation file, define a new XSL variable to contain the LDAP
attribute for the persons mentor:
<xsl:variable name="DefaultMentorAttribute">mentor</xsl:variable>

3. Add the following XML snippet to the transformation file:


<!-- Begin template ManagerOfEmployee -->
<xsl:template name="ManagerOfEmployee">
<sldap:staffQueries>
<xsl:attribute name="threshold">
<xsl:value-of select="$Threshold"/>
</xsl:attribute>
<sldap:intermediateResult>
<xsl:attribute name="name">mentorvar</xsl:attribute>
<sldap:user>
<xsl:attribute name="dn">
<xsl:value-of select="staff:parameter[@id=EmployeeName]"/>
</xsl:attribute>
<sldap:resultObject>
<xsl:attribute name="objectclass">
<xsl:value-of select="$DefaultPersonClass"/>
</xsl:attribute>
<xsl:attribute name="usage">simple</xsl:attribute>
<sldap:resultAttribute>
<xsl:attribute name="name">
<xsl:value-of select="$DefaultMentorAttribute"/>
</xsl:attribute>
<xsl:attribute name="destination">intermediate</xsl:attribute>
</sldap:resultAttribute>
</sldap:resultObject>

<sldap:user>
<xsl:attribute name="dn">%mentorvar%</xsl:attribute>
<xsl:call-template name="ResultObjectSpecForUserData"/>
</sldap:user>
</sldap:staffQueries>
</xsl:template>
<!-- End template ManagerOfEmployee -->

Chapter 2. About human tasks

87

Substitution for absentees


The substitution feature allows you to specify absence settings either for yourself,
or for members of the group that you administer. A substitution policy defines
how to deal with tasks and escalations that are assigned to absent users.
The substitution policy is defined when the task template is modeled. The same
policy is applied for all of the task roles that are associated with a task template.
After the task template is deployed, you cannot change the policy.
If a user is absent, the substitution policy is applied to the results of the people
resolution to determine who receives the work items instead of the absent user. It
is applied only to task roles that have people assignment criteria. This means that
task originators, starters, or owners are not subject to substitution. Similarly,
substitution is refreshed if the people assignment criteria get refreshed.
Depending on the specific substitution policy, the following actions are applied:
No substitution (default)
The set of users remains unchanged
Substitute if the user is absent
v For every user that is present, the user itself is used.
v For every user that is absent, the first substitute that is present is used.
v If none of the users and none of their substitutes are present, then the
default people assignment rules apply.
Select user if present
v For every user that is present, the user is used.
v Substitutes are not taken into account.
v If none of the users is present, then the original set of users is used, that
is, the fact that they are absent is disregarded.
The substitution feature requires virtual member manager as the people directory.
To make virtual member manager available for substitution, the federated
repositories must be configured as the active security realm in WebSphere
Application Server. Ensure that you enable substitution for Human Task Manager
in the administrative console. If you deploy a task template with a non-default
substitution policy to a people directory provider other than virtual member
manager, the deployment fails.
Related tasks
Configuring people substitution on page 199
This topic describes how to configure people substitution for Business Process
Choreographer.
Specifying absence settings on page 355
If you intend to be away from the office for a certain time, specify a substitute
for your tasks.
Specifying absence settings for users on page 356
If users are prevented from working on their tasks, for example, if they are on
sick leave, specify a substitute for the users tasks.

Default people assignments and inheritance rules


Default people assignments are performed if you do not define people assignment
criteria for certain task roles, or if people resolution fails or does not return a
result. The default assignments differ for inline tasks and stand-alone tasks.

88

Business Process Choreographer

Inheritance rules are applied to automatically assign people to a particular role,


based on the fact that they are already assigned to another role. Inheritance rules
effectively add users to a role in addition to the users that are determined by
people assignment. These rules differ for inline tasks and stand-alone tasks.

Inline tasks
The following table shows the default people assignments for inline tasks.
Roles for inline human
tasks and their escalations

If the role is not defined in


the task model ...

If people assignment fails...

Task administrator

Only inheritance applies

Only inheritance applies

Task potential instance


creator

Everybody becomes potential


instance creator

Everybody becomes potential


instance creator

Task potential starter

Everybody becomes potential


starter

Everybody becomes potential


starter

Task potential owner

Everybody becomes potential


owner

Administrators become
potential owners

Task editor

No editor

No editor

Task reader

Only inheritance applies

Only inheritance applies

Escalation receiver

Administrators become
escalation receivers

Administrators become
escalation receivers

The following inheritance rules apply to inline tasks:


v Process administrators become administrators for all inline tasks, their subtasks,
follow-on tasks, and escalations.
v Process readers become readers for all inline tasks, their subtasks, follow-on
tasks, and escalations.
v Task administrators become administrators for all subtasks, follow-on tasks, and
escalations of all these tasks.
v Task readers become readers for all subtasks, follow-on tasks, and escalations of
all these tasks.
v Members of any task role become readers for this tasks escalations, subtasks,
and follow-on tasks.
v Escalation receivers become readers for the escalated task.

Stand-alone tasks
The following table shows the default people assignments for stand-alone tasks.
Roles for stand-alone
human tasks and their
escalations

If the role is not defined in


the task model ...

If people assignment fails...

Task administrator

Originator becomes
administrator

The task is not started

Task potential instance


creator

Everybody becomes potential Everybody becomes potential


instance creator
instance creator

Task potential starter

Originator becomes potential The task is not started


starter

Potential owner

Everybody becomes potential Administrators become


owner
potential owners
Chapter 2. About human tasks

89

Roles for stand-alone


human tasks and their
escalations

If the role is not defined in


the task model ...

If people assignment fails...

Editor

No editor

No editor

Reader

Only inheritance applies

Only inheritance applies

Escalation receiver

Administrators become
escalation receivers

Administrators become
escalation receivers

The following inheritance rules apply to stand-alone tasks:


v Task administrators become administrators for all subtasks, follow-on tasks, and
escalations of all these tasks.
v Task readers become readers for all subtasks, follow-on tasks, and escalations of
all these tasks.
v Members of any task role become readers for this tasks escalations, subtasks,
and follow-on tasks.
v Escalation receivers become readers for the escalated task.
When a method is invoked using the Business Flow Manager API, members of the
BPESystemAdministrator role have administrator authorization, and members of
the BPESystemMonitor role have reader authorization. When a method is invoked
via the Human Task Manager API, members of the TaskSystemAdministrator role
have administrator authorization, and members of the TaskSystemMonitor role
have reader authorization.
Related concepts
Authorization roles for human tasks on page 68
Actions that you can take on human tasks depend on your authorization role.
This role can be a system-level J2EE role or an instance-based role.

Managing people assignment criteria and people resolution


results
A people assignment criteria that is associated with a task authorization role is
valid throughout the lifetime of a deployed task template or task instance.
If you need to change the people assignment criteria, you must change the task
definition in WebSphere Integration Developer, and deploy the task template again.
The people query that is derived from the people assignment criteria is stored as
part of the deployed task template, or task instance. During the execution of a task,
the authorization roles require the resolution of the associated people queries.
The result of a people query depends on the content of the people directory, which
might change over time. For example, new members might be added to a people
group. To reflect changes in the people directory, a people query must be refreshed
in one of the following ways:
v Explicitly by an administrator
An administrator can use either the administrative console or the administrative
commands to refresh people query results. Commands exist for the following
actions:
Refreshing all of the people query results at once
Refreshing all of the people query results that are associated with a task
template

90

Business Process Choreographer

Refreshing people query results that contain a specific user ID in the current
result.
v Triggered by a scheduled refresh of expired people queries
This approach is based on the following parameters:
A timeout value for people query results (Tout).
A refresh schedule for the people query. Use the WebSphere Application
Server CRON-syntax for defining the schedule, for example, every Monday at
1 pm, or every work-day at midnight.
The following parameters determine how people queries are automatically
refreshed:
When a query is run for the first time or it is refreshed, the query result gets
an expiration timestamp (texp = tcurrent + Tout)
When the query refresh daemon is invoked, all of the people queries with
results that have expired are run again
You can set the timeout value to be above the schedule refresh interval. For
example, you can set the timeout value to be 24h, and the refresh interval to 1h.
In this way, you can spread the updates to the people queries throughout the
day and avoid the overhead of refreshing all of the people query results at once.
Related tasks
Refreshing people query results, using the administrative console on page 287
The results of a people query are static. Use the administrative console to
refresh people queries.
Refreshing people query results, using administrative scripts on page 306
The results of a people query are static. Use the administrative scripts to refresh
people queries.
Refreshing people query results, using the refresh daemon on page 290
Use this method if you want to set up a regular and automatic refresh of all
expired people query results.

Sharing people assignments


For a specific task role, the same people assignment criteria are used in all
instances of a task template. This is because all of the task instances are
instantiated from the same task template. To avoid rerunning people queries, the
result of a query is shared across task instances of a task template.
The sharing of results applies only if a people assignment criteria definition
contains fixed parameter values. Such values, for example, the name of a group:
cn=group1, cn=groups, imply that the corresponding people query result is the
same, regardless of the task instance context in which the people query is resolved.
If the people assignment criteria definition contains replacement variables, the
sharing scope is reduced to people assignments that have the same replacement
variable values. For example, a parameter value can depend on parts of the input
message of a task. Because different task instances can have different input
messages, the parameter values for the people queries differ, too.
If you post process people query results, sharing does not apply to these results by
default. To enable the sharing of post-processed results, complete the following
steps in the administrative console:
1. If Business Process Choreographer is configured on a server, click Servers
Application Servers server_name.

Chapter 2. About human tasks

91

2. If Business Process Choreographer is configured on a cluster, Servers Clusters


cluster_name.
3. Under Business Integration, click Business Process Choreographer Human
Task Manager [Additional Properties] Custom Properties.
4. Change the value of the Staff.PostProcessorPlugin.EnableResultSharing
custom property to true, and save your changes
5. Restart the server or cluster to make the changes effective.
Related tasks
Creating and installing plug-ins to post-process people query results on page
533
People resolution returns a list of the users that are assigned to a specific role,
for example, potential owner of a task. You can create a plug-in to change the
results of people queries returned by people resolution. For example, to
improve workload balancing, you might have a plug-in that removes users
from the query result who already have a high workload.

92

Business Process Choreographer

Part 2. Planning and configuring Business Process


Choreographer

Copyright IBM Corp. 2006, 2008

93

94

Business Process Choreographer

Chapter 3. Planning to configure Business Process


Choreographer
Plan your Business Process Choreographer setup and configuration parameters.
Procedure
1. Perform Planning the topology, setup, and configuration path.
2. Depending on your chosen configuration path, perform one of the following:
v For Basic sample, perform Planning to create a basic sample Business
Process Choreographer configuration on page 101.
v For Sample with organization, perform Planning to create a sample
Business Process Choreographer configuration including a sample
organization on page 102.
v For Non-production deployment environment, perform Planning a
non-production deployment environment configuration on page 103.
v For Production deployment environment, perform Planning to use the
administrative consoles deployment environment wizard on page 104.
v For Flexible custom configuration, perform Planning for a custom
Business Process Choreographer configuration on page 109.
Results
You have planned everything you need to be able to perform Chapter 4,
Configuring Business Process Choreographer, on page 141.
Related concepts
About Business Process Choreographer on page 135
Describes the facilities provided by the Business Flow Manager and the Human
Task Manager.

Planning the topology, setup, and configuration path


Your choice of topology and setup affects which Business Process Choreographer
configuration paths you can use.
About this task
The different configuration paths vary in complexity, flexibility, and their support
for different topologies and databases.
Procedure
1. Be aware that you must choose between five different configuration paths.
v Basic sample
v Sample with organization
v Non-production deployment environment
v Production deployment environment
v Flexible custom configuration
For most configuration paths, you have a choice of configuration tools.

IBM Corporation 2002, 2007

95

2. Be aware of the different configuration tools that you can use to configure
Business Process Choreographer.
Installer or Profile Management Tool
Provide the easiest ways to create a non-production system, and they
require the least planning.
v The Basic sample configuration includes the following Business
Process Choreographer components:
Business Process Choreographer
Explorer
Observer and event collector
v The Sample with organization configuration also includes a people
directory that is preconfigured with 15 users in a sample
organization, and has substitution and group work items enabled.
v The Non-production deployment environment configuration
provides an easy way to configure Business Process Choreographer
on a cluster, but Business Process Choreographer cannot have its
own database, instead, it uses the common WPRCSDB database.
Administrative consoles deployment environment wizard
Can be used to create a Production deployment environment
Business Process Choreographer configuration, based on a deployment
environment pattern.
Administrative consoles Business Process Choreographer configuration page
You can use this administrative console page to configure a Flexible
custom configuration Business Process Choreographer production
system on a server or cluster. It provides the opportunity to set many
configuration parameters, which need detailed planning. This page
does not configure the Business Process Choreographer Explorer or
Business Process Choreographer Observer; they have their own
configuration pages, or can be configured by running scripts. This
configuration path is most suitable for creating production systems.
bpeconfig.jacl configuration script
You can use this script to configure a Flexible custom configuration
Business Process Choreographer production system and all the
necessary resources on a given server or cluster. You can run the script
interactively, or if you provide all the necessary parameters, it can run
in batch mode for repeatable automation. It can create a local database,
the necessary messaging resources, and can optionally configure the
Business Process Choreographer Explorer and Business Process
Choreographer Observer. For some database systems, it can also create
a remote database. This configuration path is most suitable for creating
production systems.
3. Be aware that some of the configuration paths have restrictions that limit their
suitability for production systems: For example:
v After experimenting with one of the sample configurations, it must be
removed before you can create a configuration that is suitable for a
production system.
v If you create a configuration that uses a Derby Embedded database, or the
common WPRCSDB database, it will not be suitable for a high-performance
system. You must remove the configuration before you can create a new
configuration that uses a separate high-performance database.

96

Business Process Choreographer

v If your message store uses either a file store or Derby Embedded data store,
you cannot federate the profile into a network deployment environment. To
be able to federate the profile, you would have to completely remove your
Business Process Choreographer configuration and create a new
configuration that uses a remotely accessible database for the message store.
4. Identify the main criteria for deciding which configuration path to use. Use the
following table to identify choices and constraints:
Table 4. Criteria for selecting a configuration path
Suitable
for a
Deployproduction ment
system?
target

Business Process
Choreographer
configuration

Can have a
separate
BPEDB
database?

Basic sample

Only Derby
Embedded

(without the sample


organization)

Standalone
server

Sample including a 15
person organization,
and substitution is
enabled.

Message
stores
supported for
the messaging Suitable configuration name, tools,
engine
and options

Select the options:


v Stand-alone server profile
v Typical
v Enable administrative security
Yes, but
only Derby
Embedded

Derby
Embedded,
File Store, or
WPRCSDB

No, it
shares
WPRCSDB,
which can
be any
database
except
Derby
Embedded

Shares
WPRCSDB,
which can be
any supported
database
except File
Store and
Derby
Embedded

This sample is identical


to the sample that is
available in WebSphere
Integration Developer
when you include the
WebSphere Test
Environment.

No

Choice of deployment
environment patterns:
Cluster

v Remote Messaging
and Remote Support
v Remote Messaging
v Single Cluster

Basic sample using one of:


v Installer
v Profile Management Tool

Sample with organization using:


v Profile Management Tool
Select the options:
v Stand-alone server profile
v Advanced
v Create server from development
template
v Enable administrative security

Non-production deployment
environment using one of:
v Installer
v Profile Management Tool
Select: Deployment environment

Chapter 3. Planning to configure Business Process Choreographer

97

Table 4. Criteria for selecting a configuration path (continued)


Suitable
for a
Deployproduction ment
system?
target

Business Process
Choreographer
configuration
Choice of deployment
environment patterns:
v Remote Messaging
and Remote Support
v Remote Messaging
v Single Cluster

Cluster

Can have a
separate
BPEDB
database?
Yes, any
supported
database
except
Derby
Embedded

Message
stores
supported for
the messaging Suitable configuration name, tools,
engine
and options
Any
supported
database
except File
Store and
Derby
Embedded

Production deployment
environment using:
v Administrative console
Select: Deployment environment

v Custom

Yes

Flexible custom
configuration

Yes, any
supported
database

Any
supported
database
except File
Store and
Derby
Embedded

Flexible custom configuration


using one of:
v bpeconfig.jacl script
v Administrative console Business
Process Choreographer
configuration page

Any
supported
database, or
File Store

Standalone
server

Note: It is also possible to use any of the configuration paths that are
recommended for creating a production system to create a configuration that is
not suitable for a production system.
Consider the following options:
a. Decide whether you are configuring a production system. Typically a
production system requires high-performance, scalability, and security. For
Business Process Choreographer, a production system should have its own
non-Derby BPEDB database.
b. Decide whether the deployment target for the Business Process
Choreographer will be a stand-alone server or a cluster.
c. If you do not want to create a production system, decide whether a sample
configuration on a stand-alone server will meet your needs. If so, decide
whether you want the sample to include a sample people directory
(populated with a sample organization) for people assignment and
substitution enabled.
Note: The sample people directory uses the default file registry configured
for the federated repositories, and includes all sample people with the same
password wid. The WebSphere administration user ID is also added to
the directory, using the password that was specified during profile creation.
After the sample configuration has been created, you can use the
administrative console to view which users and groups are available by
clicking Users and Groups, then either Manage Users or Manage Groups.
d. If you want to configure Business Process Choreographer on a cluster,
depending on your performance requirements, decide whether the
messaging engines and supporting applications, (such as the Business

98

Business Process Choreographer

Process Choreographer Explorer, Observer, and Common Event


Infrastructure) will have their own cluster, or share one. The standard
deployment environment patterns are:
Remote Messaging and Remote Support
Three clusters are used. One each for the applications, messaging
engines, and support applications.
Remote Messaging
One cluster is used for the applications and support functions. A
second cluster is used for the messaging engines.
Single cluster
Only one cluster is used for applications, messaging engines, and
support applications.
Custom
More flexible setup.
e. Decide whether you want a dedicated BPEDB database for Business Process
Choreographer.
f. Decide which message store the Business Process Choreographer messaging
engine will use.
v Its own message store, which can either be a file store or a database
system.
v Share a separate MEDB database that is used by all messaging engines in
the cell.
v Share the WPRCSDB database.
g. If you want to use the Business Process Choreographer Observer, you can
either configure it at the same time as you create a Business Process
Choreographer configuration, or you can create it later. Decide whether
Business Process Choreographer Observer will also use the BPEDB
database, or whether it will have its own, OBSRVRDB, database. Also plan
the topology for the Business Process Choreographer Observer components.
To perform the detailed planning now, perform Planning for the Business
Process Choreographer Observer on page 132.
5. If you want WebSphere Portal to access Business Process Choreographer, plan
to create a WebSphere Process Server client installation on the portal server,
using a WebSphere Process Server client that is the same version number as the
application server on which the portal server is based. Similarly, you can create
a WebSphere Process Server client installation to enable any custom WebSphere
Process Server client application to access Business Process Choreographer.
6. If you want a remote Business Process Choreographer client application that
runs in a WebSphere Process Server client installation, perform Planning for a
remote client application on page 100.
7. If you have application security enabled and you have a long-running process
that calls a remote EJB method, Common Secure Interoperability Version 2
(CSIv2) identity assertion must be enabled when you configure CSIv2 inbound
authentication.
Results
You have planned the topology and know which configuration path and
configuration tool you will use.
Related tasks

Chapter 3. Planning to configure Business Process Choreographer

99

Planning for a remote client application


Planning for a remote Business Process Choreographer client application that
uses the Business Process Choreographer APIs and runs on a WebSphere
Process Server client installation.
Related information
Profiles
Deployment Environment Patterns

Planning for a remote client application


Planning for a remote Business Process Choreographer client application that uses
the Business Process Choreographer APIs and runs on a WebSphere Process Server
client installation.
About this task
If you want an application to use the Business Process Choreographer APIs, you
can use a WebSphere Process Server client installation to run the applications
remotely against a full WebSphere Process Server server installation. The client is
easier to configure and administer than a full WebSphere Process Server
installation.
The WebSphere Process Server client installation does not contain WebSphere
Process Server profile templates, and does not need to augment the underlying
WebSphere Application Server profile. This means that you can even install the
WebSphere Process Server client on top of an existing WebSphere Application
Server installation that has federated profiles and those federated WebSphere
Application Server profiles can take advantage of the WebSphere Process Server
client functionality immediately. This scenario is not possible with the full
WebSphere Process Server server because WebSphere Process Server does not
support augmentation of already federated profiles.
Procedure
1. Plan to install a WebSphere Process Server client.
v You can install it on an existing WebSphere Application Server that matches
the version of the WebSphere Process Server client, for example, WebSphere
Portal Server 6.0.1 includes WebSphere Application Server 6.0.2, which would
need a WebSphere Process Server 6.0.2 client installation. Any existing
profiles, including already federated profiles, can use WebSphere Process
Server client immediately, because the client installation does not augment
the base profile.
v If there is no existing WebSphere Application Server installation, a
WebSphere Application Server network deployment installation will be
created.
2. Decide which type of Business Process Choreographer client application you
will use:
v Custom client application
v Business Process Choreographer Explorer
Note: If you use customized JavaServer Pages (JSP), as described in
Chapter 15, Developing JSP pages for task and process messages, on page
523, make sure that you know where they are located.

100

Business Process Choreographer

3. If you are going to develop a custom client application that will use Business
Process Choreographer, plan which interfaces the application will use. You can
handle processes and tasks using one of the following:
v Web services API or Java Messaging Service (JMS) API remote client
applications that are based on these APIs do not need any WebSphere
Process Server installation.
v JavaServer Faces (JSF) components
v Enterprise JavaBeans (EJB) API
Note: If you develop a client application, which uses the Business Process
Choreographer EJB APIs, it must be packaged in the way that is described in
Accessing the remote interface of the session bean on page 392.
4. Decide or identify the type of cell where the WebSphere Process Server client
will be installed:
a. In a cell where a managed server or cluster is located, on which Business
Process Choreographer is configured, the default configuration of the
Remote Artifact Loader (RAL) allows the unsecured transmission of artifacts
between the client and the server. This is known as the single-cell
scenario.
b. In a cell that does not have a managed server or cluster with Business
Process Choreographer configured on it, there are different deployment
managers. This is known as the cross-cell scenario. If your client
application uses the EJB API, you must define a namespace binding so that
the client application can locate the server or cluster where Business Process
Choreographer is configured.
Results
You have planned for a remote Business Process Choreographer client application.

Planning to create a basic sample Business Process Choreographer


configuration
This basic sample, for a stand-alone server, does not include a sample organization.
Before you begin
You have performed Planning the topology, setup, and configuration path on
page 95, and have selected the Basic sample configuration path.
Procedure
1. Decide whether you will create the sample using the Installer or Profile
Management Tool.
2. If you decided to use the Profile Management Tool, decide whether the
Business Process Choreographer messaging engine will use file store, an
embedded Derby database, or the common, WPRCSDB, database.
3. If you want the Human Task Manager to be able to send escalation e-mails,
plan the following:
v If there will not be a local Simple Mail Transfer Protocol (SMTP) mail server
available, plan to change the mail session later to point to a suitable mail
server.
v Plan to change the sender address for the e-mails. Otherwise, it will use a
dummy sender address.
Chapter 3. Planning to configure Business Process Choreographer

101

4. Be aware that this sample configuration uses the WebSphere administrator user
ID and password for the various Business Process Choreographer user IDs.
Results
You have planned to create a basic sample Business Process Choreographer
configuration.

Planning to create a sample Business Process Choreographer


configuration including a sample organization
This sample includes a 15 person sample organization, which is suitable for
experimenting with people assignment and substitution on a stand-alone server.
This sample is identical to the sample that is available in WebSphere Integration
Developer when you include the WebSphere Test Environment.
Before you begin
You have performed Planning the topology, setup, and configuration path on
page 95, and have selected the Sample with organization configuration path.
About this task
This sample Business Process Choreographer configuration requires minimal
planning.
Procedure
1. Decide whether the Business Process Choreographer messaging engine will use
file store, an embedded Derby database, or the common, WPRCSDB, database.
2. Be aware that this sample can only be created using the Profile Management
Tool. To get this sample, you must select the following options:
v Stand-alone server profile
v Advanced
v Create server from development template
v Enable administrative security
If for example, you do not enable administrative security, the sample Business
Choreographer configuration will not be created.
Note: The sample people directory uses the default file registry configured for
the federated repositories, and includes all sample people with the same
password wid. The WebSphere administration user ID is also added to the
directory, using the password that was specified during profile creation. After
the sample configuration has been created, you can use the administrative
console to view which users and groups are available by clicking Users and
Groups, then either Manage Users or Manage Groups.
3. If you want the Human Task Manager to be able to send escalation e-mails,
plan the following:
v If there will not be a local Simple Mail Transfer Protocol (SMTP) mail server
available, plan to change the mail session later to point to a suitable mail
server.
v Plan to change the sender address for the e-mails. Otherwise, it will use a
dummy sender address.

102

Business Process Choreographer

4. Be aware that this sample configuration uses the WebSphere administrator user
ID and password for the various Business Process Choreographer user IDs.
Results
You have planned to create a sample Business Process Choreographer
configuration including a sample organization.

Planning a non-production deployment environment configuration


Planning to use the Installer or Profile Management Tool to create a Business
Process Choreographer configuration that is based on a deployment environment
pattern.
Before you begin
You have performed Planning the topology, setup, and configuration path on
page 95, and have selected the Non-production deployment environment
configuration path.
About this task
When using the deployment environment wizard, you must select the deployment
environment pattern, then you have the opportunity to change the default
database parameters and authentication aliases for the WBI_BPC component, and
enter other parameters for Business Process Choreographer.
Procedure
1. Decide which deployment environment pattern you will use:
v Remote Messaging and Remote Support
v Remote Messaging
v Single Cluster
2. Plan the user name for the Business Process Choreographer JMS authentication
alias that you will enter during the Security step.
3. Plan the context roots for the Business Process Choreographer step:
Business Process Choreographer Explorer context root
This defines part of the URL that browsers must use to reach the
Business Process Choreographer Explorer.
Business Process Choreographer Observer context root
This defines part of the URL that browsers must use to reach the
Business Process Choreographer Observer.
4. Plan the security parameters for the Business Process Choreographer step.
These user IDs and groups will be used for the Business Flow Manager and
Human Task Manager:
Administrator User and Group
Plan a list of user IDs or a list or groups, or both, onto which the
business administrator role is mapped.
Monitor User and Group
Plan a list of user IDs or a list or groups, or both, onto which the
business monitor role is mapped.

Chapter 3. Planning to configure Business Process Choreographer

103

JMS API Authentication User and Password


The run-as user ID for the Business Flow Manager message driven
bean.
Escalation User Authentication User and Password
The run-as user ID for the Human Task Manager message driven bean.
5. If you want to configure an e-mail session for the Human Task Manager
escalations, plan the following parameters for the Business Process
Choreographer step:
Mail transport host
The hostname or IP address where the Simple Mail Transfer Protocol
(SMTP) e-mail service is located.
Mail transport user and Mail transport password
If the mail server does not require authentication, you can leave these
fields empty.
Business Process Choreographer Explorer URL
This URL is used to provide a link in generated e-mails so that a
business administrator who receives an e-mail notification can click on
the link to view the related business process or human task in their
Web browser.
6. If you are going to use the Business Process Choreographer Explorer, the
Business Space, or a client that uses the Representational State Transfer (REST)
API, decide on the context root for the REST API. The default for the Business
Flow Manager is /rest/bpm/bfm. The default for the Human Task Manager is
/rest/bpm/htm.
v When configured on a server, or on a single cluster, or on multiple clusters
that are mapped to different Web servers, you can use the default values.
v When configured in a network deployment environment on multiple
deployment targets that are mapped to the same Web server, do not use the
default values. The context root for each Business Process Choreographer
configuration must be unique for each combination of host name and port.
You will have to set these values manually using the administrative console
after configuring Business Process Choreographer.
7. If you want to use people assignment, perform Planning for the people
directory provider on page 130.
Results
You have planned to create a non-production deployment environment
configuration.

Planning to use the administrative consoles deployment environment


wizard
For a production system plan all the configuration parameters for Business Process
Choreographer, including a separate database. For a non-production system you
can use a shared database.
Before you begin
You have performed Planning the topology, setup, and configuration path on
page 95, and have selected the Production deployment environment
configuration path.

104

Business Process Choreographer

About this task


When using the deployment environment wizard, you must select the deployment
environment pattern, then you have the opportunity to change the default
database parameters and authentication aliases for the WBI_BPC component, and
enter other parameters for Business Process Choreographer.
Procedure
1. If you do not have enough information or authority to create the whole
configuration on your own, consult and plan with the people who are
responsible for other parts of the system. For example:
v You might need to request information about your organizations LDAP
server, if it uses authentication you will need to request a user ID, and
authorization.
v If you are not authorized to create the database, your database
administrator must be included in planning the databases, and will need a
copy of the database scripts to customize and run.
2. Perform Planning security, user IDs, and authorizations on page 110.
3. Decide which deployment environment pattern you will use:
v Remote Messaging and Remote Support
v Remote Messaging
v Single Cluster
v Custom
4. If you chose the Custom deployment environment pattern:
a. Decide if you want to install the Business Process Choreographer Explorer.
If so, plan where you will deploy it.
b. Decide if you want to install the Business Process Choreographer event
collector. If so, plan where you will deploy it.
c. Decide if you want to install the Business Process Choreographer Observer.
If so, plan where you will deploy it.
d. Plan the context root for the SCA bindings.
e. Plan whether you want to enable or disable the state observers and audit
logging.
5. If you are planning to have dedicated databases for the following:
v The BPEDB database for Business Process Choreographer component
WBI_BPC.
v The OBSRVRDB database for the Business Process Choreographer Observer
component WBI_BPCEventCollector.
v The BPEMEDB database for the Business Process Choreographer messaging
engine component WBI_BPC_ME.
Plan the following parameters for each database, to enter on the wizards
database page:
Database Instance
The name of the data source, for example, BPEDB, OBSRVRDB, or BPEMEDB
instead of the default value, WPRCSDB, which results in sharing the
common database. The default value is only suitable for lower
performance setups.
Schema
The database schema qualifier to be used.
Chapter 3. Planning to configure Business Process Choreographer

105

Create Tables
If selected, the tables will be created automatically the first time that
the database is accessed. For this option to work, the database must
already exist, and the user name provided for creating the data source
must have the authority to create tables and indexes in the database.
If not selected, the tables will not be created automatically, and you
must create the tables manually by running scripts. For a production
system, clear this option, and plan to use the provided SQL scripts to
setup the database.
User Name and Password
A user ID that has the authority to connect to the database and to
modify the data. If the user ID has the authority to create tables and
indexes in the database, then the option to create the tables
automatically can be used, and when necessary, the database schema
will be updated automatically after applying a service or fix pack.
Server The address of the database server. Specify either the host name or the
IP address.
Provider
The JDBC provider.
Also plan the database-specific settings, which you can set using the Edit
button for the JDBC provider.
Table 5. Database-specific settings
Database / JDBC driver type

Database-specific settings

DB2 UDB Universal driver

v User name
v Password
v Database name
v Schema name
v Server name
v Server port number
v Driver type
v Description
v Create tables

DB2 UDB Runtime Client

v User name
v Password
v Database name
v Schema name
v Description
v Create tables

DB2 for i5/OS Native driver

v User name
v Password
v Database name
v Collection name
v Description
v Create tables

106

Business Process Choreographer

Table 5. Database-specific settings (continued)


Database / JDBC driver type

Database-specific settings

DB2 for i5/OS Toolbox driver

v User name
v Password
v Database name
v Collection name
v Server name
v Description
v Create tables

DB2 for z/OS V8 and V9

v Implementation type Connection pool


data source or XA data source
v User name
v Password
v Database name
v Schema name
v Server name
v Server port number
v Storage group
v Description

Derby Network Server

v User name
v Password
v Description
v Create tables

Derby Embedded

v Description
v Create tables

Microsoft SQL Server Embedded and data


direct drivers

v User name
v Password
v Database name
v Server name
v Server port number
v Description
v Create tables

Informix Dynamic Server

v User name
v Password
v Server name
v Server port number
v ifxIFXHOST
v Infomix lock mode wait
v Description
v Create tables

Chapter 3. Planning to configure Business Process Choreographer

107

Table 5. Database-specific settings (continued)


Database / JDBC driver type

Database-specific settings

Oracle 10g and Oracle 11g oci8 driver

v User name
v Password
v Database name
v Schema name
v Driver type oci8
v Description
v Create tables

Oracle 10g and Oracle 11g thin driver

v User name
v Password
v Database name
v Schema name
v Server name
v Server port number
v Driver type thin
v Description
v Create tables

For more details about planning the databases, see Planning the databases
for Business Process Choreographer on page 116.
6. Plan the user name for the Business Process Choreographer JMS
authentication alias that you will enter during the Security step.
7. Plan the context roots for the Business Process Choreographer step:
Business Process Choreographer Explorer context root
This defines part of the URL that browsers must use to reach the
Business Process Choreographer Explorer.
Business Process Choreographer Observer context root
This defines part of the URL that browsers must use to reach the
Business Process Choreographer Observer.
8. Plan the security parameters for the Business Process Choreographer step.
These user IDs and groups will be used for the Business Flow Manager and
Human Task Manager:
Administrator User and Group
Plan a list of user IDs or a list or groups, or both, onto which the
business administrator role is mapped.
Monitor User and Group
Plan a list of user IDs or a list or groups, or both, onto which the
business monitor role is mapped.
JMS API Authentication User and Password
The run-as user ID for the Business Flow Manager message driven
bean.
Escalation User Authentication User and Password
The run-as user ID for the Human Task Manager message driven
bean.
9. If you want to configure an e-mail session for the Human Task Manager
escalations, plan the following parameters for the Business Process
Choreographer step:

108

Business Process Choreographer

Mail transport host


The hostname or IP address where the Simple Mail Transfer Protocol
(SMTP) e-mail service is located.
Mail transport user and Mail transport password
If the mail server does not require authentication, you can leave these
fields empty.
Business Process Choreographer Explorer URL
This URL is used to provide a link in generated e-mails so that a
business administrator who receives an e-mail notification can click on
the link to view the related business process or human task in their
Web browser.
10. If you are going to use the Business Process Choreographer Explorer, the
Business Space, or a client that uses the Representational State Transfer (REST)
API, decide on the context root for the REST API. The default for the Business
Flow Manager is /rest/bpm/bfm. The default for the Human Task Manager is
/rest/bpm/htm.
v When configured on a server, or on a single cluster, or on multiple clusters
that are mapped to different Web servers, you can use the default values.
v When configured in a network deployment environment on multiple
deployment targets that are mapped to the same Web server, do not use the
default values. The context root for each Business Process Choreographer
configuration must be unique for each combination of host name and port.
You will have to set these values manually using the administrative console
after configuring Business Process Choreographer.
11. If you want to use people assignment, perform Planning for the people
directory provider on page 130.
Results
You have planned to use the administrative consoles deployment environment
wizard.
Related tasks
Deployment environment patterns

Planning for a custom Business Process Choreographer configuration


Plan the configuration parameters and options for creating a custom configuration,
using either the Administrative consoles Business Process Choreographer
configuration page or the bpeconfig.jacl configuration script.
Before you begin
You have performed Planning the topology, setup, and configuration path on
page 95, and have selected the Flexible custom configuration configuration path.
Procedure
1. Know which of the following you will use to configure Business Process
Choreographer:
v Administrative consoles Business Process Choreographer configuration
page
v The bpeconfig.jacl configuration script

Chapter 3. Planning to configure Business Process Choreographer

109

2. If you do not have enough information or authority to create the whole


configuration on your own, consult and plan with the people who are
responsible for other parts of the system. For example:
v You might need to request information about your organizations LDAP
server, if it uses authentication you will need to request a user ID, and
authorization.
v If you are not authorized to create the database, your database
administrator must be included in planning the databases, and will need a
copy of the database scripts to customize and run.
3. Planning security, user IDs, and authorizations
4. Planning the databases for Business Process Choreographer on page 116
5. Planning for the Business Flow Manager and Human Task Manager on page
128
6. Planning for the people directory provider on page 130
7. Planning for the Business Process Choreographer Explorer on page 132
8. Planning for the Business Process Choreographer Observer on page 132
9. If you will use the Administrative consoles Business Process Choreographer
configuration page, make sure that you have planned all the values that you
will enter on the configuration page.
10. If you will use the bpeconfig.jacl configuration script:
a. Make sure that you have planned all the options and parameter values
that you must specify on the command-line, or in a batch file. The options
and parameters are summarized in Using the bpeconfig.jacl script to
configure Business Process Choreographer on page 150, and are described
in detail in bpeconfig.jacl script file on page 157.
b. If you will use a batch file to run the bpeconfig.jacl configuration script,
create the batch file or shell script.
Results
You have planned everything you need to be able to perform Chapter 4,
Configuring Business Process Choreographer, on page 141.

Planning security, user IDs, and authorizations


Plan the user IDs and authorizations for configuring Business Process
Choreographer.
About this task
During configuration, you need to use various user IDs and you must specify
other user IDs that will be used at runtime. Make sure that you plan and create all
user IDs before you start configuring Business Process Choreographer.
For a sample Business Process Choreographer configuration:
You only need the authority to create a new profile. In the Profile
Management Tool, using the option to create a typical profile, when you
enable administrative security, the Business Process Choreographer sample
will also be configured. No other planning or user IDs are required, and
you can skip this task.
For a high security configuration:
You must plan all user IDs in detail as described in this task.

110

Business Process Choreographer

For a low security configuration:


If you do not require full security, for example for a non-production
system, you can reduce the number of user IDs that are used. You must
plan all user IDs in detail, but you can use certain user IDs for multiple
purposes. For example, the database user ID used to create the database
schema can also be used as the data source user name to connect to the
database at runtime.
If you will use the bpeconfig.jacl script to configure Business Process
Choreographer:
The user ID used to run the bpeconfig.jacl script must have the necessary
rights for the configuration actions that the script will perform. Otherwise,
you must specify user IDs as parameters for the script that have the
necessary rights, in which case you must plan all user IDs in detail. For
user IDs that can be specified as parameters to the bpeconfig.jacl script, the
parameter names are included in the table.The profile must already exist. If
WebSphere administrative security is enabled, you need a WebSphere
administrator user ID in the configurator role that you can use to invoke
the wsadmin tool.
Procedure
1. Print a hardcopy of this page so that you can write your planned values in
the last column. Keep it for reference when you are configuring Business
Process Choreographer, and keep it in your records for future reference.
2. Plan the user ID you will use on the WebSphere Process Server to configure
Business Process Choreographer.
Table 6. Planning user IDs for WebSphere Process Server
User ID or role

When the user


ID is used

The user who


Configuring
configures
Business Process
Choreographer

What the user ID is


used for

Which rights the user ID must have

Logging onto the


administrative console
and running
administrative scripts.

WebSphere administrator or configurator


role, if WebSphere administrative
security is enabled.

If you are going to run


the bpeconfig.jacl script
to configure the
Business Process
Choreographer.

When running the script, you must also


provide any user IDs that are necessary
for the options that you select. For more
information see bpeconfig.jacl script
file on page 157.

Planned
user ID

3. Plan which people need access to subdirectories of install_root. If your security


policy does not allow these people to be granted this access, they will need to
be given copies of the files in the directories.

Chapter 3. Planning to configure Business Process Choreographer

111

Table 7. Planning access to the subdirectories of install_root


User ID or
role
Database
administrator

When the
user ID is
used

What the user ID is


used for

Configuring

Which rights the user ID must have

Planned
user ID

Running the scripts to If you use the bpeconfig.jacl script to configure


setup the following
Business Process Choreographer:
databases:
Read access to (or a copy of) the createSchema.sql
BPEDB: The database script that bpeconfig.jacl generates in a
for Business Process
subdirectory of the directory:
Choreographer.
v On Windows platforms: profile_root\
dbscripts\ProcessChoreographer\
OBSRVDB: The
v On Linux, UNIX, i5/OS, and in the UNIX
database for the
System Services (USS) on z/OS
Business Process
platforms:profile_root/dbscripts/
Choreographer
ProcessChoreographer/
Observer.
If you want to review the database script files:
Read access to (or a copy of the files in) the
database scripts provided in the directory:
v On Windows platforms: install_root\dbscripts\
ProcessChoreographer\database_type
v On Linux, UNIX, i5/OS, and in the UNIX
System Services (USS) on z/OS platforms:
install_root/dbscripts/ProcessChoreographer/
database_type
Where database_type is one of the following:
v DB2
v DB2zOSV8
v DB2zOSV9
v Db2iSeries
v Derby
v Informix
v Oracle
v SQLServer

Integration
developer

Customizing

To use people
assignment with a
Lightweight Directory
Access Protocol
(LDAP) or Virtual
Member Manager
(VMM) people
directory provider,
you will have to
customize a copy of
the sample XSL
transformation file.

Either read access to the Staff directory, or a copy


of the files in the directory:
v On Windows platforms: install_root\
ProcessChoreographer\Staff
v On Linux, UNIX, and i5/OS platforms:
install_root/ProcessChoreographer/Staff
The integration developer will also need write
access to a suitable directory to make the
customized XSL transformation file available to the
server.

4. Plan the user IDs that will be used to create, configure, and access the
database that is used by Business Process Choreographer.

112

Business Process Choreographer

Table 8. Planning user IDs for the BPEDB database


User ID or
role

When the
user ID is
used

What the user ID is used for Which rights the user ID must have

Database
Before
administrator configuring

To create the BPEDB database Create the database.


instance. For Oracle: To create
the BPEDB database.

Database
Configuring
administrator
or an
administrator
who will run
the
bpeconfig.jacl
script

You or your database


administrator must run
Business Process
Choreographer database
scripts, unless you are using
the embedded Derby
database.

For the BPEDB database: Alter tables,


connect, insert tables, and create
indexes, schemas, tables, table spaces,
and views.

Data source
user name

If you select the Create


Tables option, this user ID is
used to create the database
tables.

To use the Create Tables configuration


option, this user ID must also be
authorized to perform the following
actions on the BPEDB database: Alter
tables, connect, insert tables, and create
indexes, tables, and views.

The Business Flow Manager


and Human Task Manager
use this user ID to connect to
the BPEDB database.

This user ID must be authorized to


perform the following actions on the
BPEDB database: Connect, delete
tables, insert tables, select tables and
views, and update tables.

Configuring

If you use
the
bpeconfig.jacl
script, this is
Runtime
the -dbUser
parameter.

After applying When necessary, the database


service or a fix schema is updated
pack
automatically after applying
service. This only works if
this user ID has the necessary
database rights, otherwise
schema updates must be
performed manually.

Planned
user ID

This user ID must be authorized to


perform the following actions on the
BPEDB database: Alter, create, insert
and select tables, connect to the
database, create and drop indexes and
views.

5. If you will configure the Business Process Choreographer Observer, plan the
user IDs to use to create, configure, and access the database.
Table 9. Planning user IDs for the OBSRVRDB database
User ID or
role

When the
user ID is
used

What the user ID is used for Which rights the user ID must have

Database
Before
administrator configuring

To create the OBSRVRDB


Create the database.
database instance. For Oracle,
to create the OBSVRDB
database.

Database
Configuring
administrator
or an
administrator

Running the
setupEventCollector tool, or
SQL scripts to create the
schema.

Planned
user ID

For the OBSRVRDB database: Alter


tables, connect, create function, insert
tables, and create indexes schemas,
tables, table spaces, and views.
If you are going to use the Java
implementation of the user-defined
functions, the user ID must also be
authorized to install the JAR file.

Chapter 3. Planning to configure Business Process Choreographer

113

Table 9. Planning user IDs for the OBSRVRDB database (continued)


User ID or
role

When the
user ID is
used

What the user ID is used for Which rights the user ID must have

Event
Runtime
collector data
source user
name

Planned
user ID

Connecting to the observer


Connect to the database,
database. If you are using the
Business Process
Choreographer Observer and
it uses the BPEDB database,
use the same user name as
for the Business Process
Choreographer data source.

6. If you will have a separate database for the Business Process Choreographers
messaging engine message store (not Derby Embedded nor file store), plan the
user ID that will be used to access the database.
Table 10. Planning user ID for the preconfigured BPEME messaging engine database
User ID or role

When the user


ID is used

What the user ID is


used for

Which rights the user ID must


have

Bus data source


user name

Configuring
and runtime

This user name is used


to connect to the BPEME
database, and to create
the necessary tables and
index.

This user ID must be authorized to


perform the following actions on the
BPEME database: Connect, delete
tables, insert tables, select tables and
views, and update tables.

If you use the


bpeconfig.jacl
script, this is the
-medbUser
parameter.

Planned user
ID

7. Plan user IDs for the Java Message Service (JMS) provider.
Table 11. Planning user IDs for the JMS provider
User ID or
role
JMS
authentication
user

When the
user ID is
used
Runtime

What the user ID is used for


The authentication alias for the
system integration bus. You must
specify it when configuring
Business Process Choreographer.
If you use the bpeconfig.jacl
script, this user IDs and its
password are the parameters
-mqUser and -mqPwd.

114

Business Process Choreographer

Which rights the user ID must


have
It must be a user name that exists
in the WebSphere user registry. It
is automatically added to the Bus
Connector role for the Business
Process Choreographer bus.

Planned user
ID

Table 11. Planning user IDs for the JMS provider (continued)
User ID or
role
JMS API
authentication
user

When the
user ID is
used
Runtime

What the user ID is used for

Which rights the user ID must


have

Planned user
ID

Any Business Flow Manager JMS These must be user names that
API requests will be processed on exist in the WebSphere user
using this user ID.
registry.
If you use the bpeconfig.jacl
script, this user IDs and its
password are the parameters
-jmsBFMRunAsUser and
-jmsBFMRunAsPwd.

Escalation
authentication
user

Runtime

Any Human Task Manager JMS


API requests will be processed on
using this user ID.
If you use the bpeconfig.jacl
script, this user ID and its
password are the parameters
-jmsHTMRunAsUser and
-jmsHTMRunAsPwd.

8. Plan which groups or user IDs, the J2EE roles for the Business Flow Manager
and Human Task Manager will be mapped onto.
Table 12. Planning the security roles for the Business Flow Manager and Human Task Manager
User ID or
role

When the
user ID is
used

Administrator Runtime
user
Administrator Runtime
group
Monitor user

Runtime

What the user ID is used for

Planned list of user


IDs, groups, or both

The system administrator and monitor security roles for


both the Business Flow Manager and Human Task Manager
are each mapped to a list of user IDs, groups, or both. The
values defined here create the mapping that gives users in
this role the access rights that they need.
If you use the bpeconfig.jacl script, these users and groups
correspond to the following parameters:
v -adminBFMUsers and -adminHTMUsers

Monitor
group

Runtime

v -adminBFMGroups and -adminHTMGroups


v -monitorBFMUsers and -monitorHTMUsers
v -monitorBFMGroups and -monitorHTMGroups

9. If you want human task escalations to send notification e-mails for specific
business events, and your Simple Mail Transfer Protocol (SMTP) server
requires authentication, decide which user ID will be used to connect to the
e-mail server.

Chapter 3. Planning to configure Business Process Choreographer

115

Table 13. Planning the user ID for the e-mail server


When the
user ID is
used

User ID or
role
Mail
transport
user

Runtime

Which rights the user


ID must have

What the user ID is used for

Planned user
ID

The Human Task Manager uses this user ID Send e-mails.


to authenticate against the configured mail
server to send escalation e-mails.
If you use the bpeconfig.jacl script, this is
the -mailUser parameter. The password is
the -mailPwd parameter.

10. If you will use people assignment for human tasks, and you will use a
Lightweight Directory Access Protocol (LDAP) people directory provider that
uses simple authentication, plan the user ID that will be used to log on to the
LDAP server.
Table 14. Planning the user ID for the LDAP server
When the
user ID is
used

User ID or
role
LDAP plug-in
property:
Authentication
Alias

Runtime

What the user ID is used for


When configuring a Lightweight
Directory Access Protocol (LDAP)
people directory provider that uses
simple authentication to connect to
LDAP, for example, mycomputer/My
LDAP Alias. You specify this user ID
when customizing the properties for
the LDAP plug-in.

Which rights the user ID must


have

Planned
user ID

If the LDAP server uses simple


authentication, this user ID must
be able to connect to the LDAP
server. If the LDAP server uses
anonymous authentication this
user ID is not required.

11. Create the user IDs that you have planned with the necessary authorizations.
If you do not have the authority to create them all yourself, submit a request
to the appropriate administrators, and enter the names of the user IDs that
they create for you in this table.
Results
You know which user IDs will be required when configuring Business Process
Choreographer.

Planning the databases for Business Process Choreographer


Plan the databases for Business Process Choreographer. Depending on your setup,
you might need to plan to create up to three databases, or none.
About this task
Business Process Choreographer can share a database with other process server
components. The BPEDB database is used by the Business Flow Manager and the
Human Task Manager. For a production system plan to have a dedicated database
for each deployment target where Business Process Choreographer is configured. If
you are using the Business Process Choreographer Observer, it can use the same
BPEDB database, but using an additional database, OBSRVDB, gives better
performance. The Business Process Choreographer messaging engines can either
share the database used by the SCA messaging engines, or have their own
BPEMEDB database. For more information about which databases are supported
for your selected configuration path, see Table 4 on page 97.

116

Business Process Choreographer

Procedure
1. For a production system:
a. If performance is important, plan to use a separate database for Business
Process Choreographer, as described in Planning the BPEDB database,
otherwise, plan to use the WPRCSDB common database.
b. If you will use the Business Process Choreographer Observer:
v If you want to minimize the impact that its queries have on the
performance of your business processes, plan to use a separate database
as described in Planning the OBSRVRDB database on page 123.
v Otherwise, plan to configure it to use the BPEDB database.
c. For high-load setups, for example, a large cluster with very high messaging
rates, consider improving the performance by using a separate database for
the Business Process Choreographer messaging engine. This allows the
database logging to be parallelized, which can help to prevent it from
becoming a bottleneck. If you want a separate database for the Business
Process Choreographer messaging engine, perform Planning the messaging
engine database on page 127, otherwise plan to use the default database
that is used by the Service Component Architecture (SCA).
2. For a non-production system where simplicity of setup is more important than
performance, your options depend on the configuration path that you have
chosen:
v If you will use the Installer or Profile Management Tool to create the Basic
sample or the Sample with organizationBusiness Process Choreographer
configuration, a separate Derby BPEDB database is created, which is also
used by the Business Process Choreographer Observer. For the Business
Process Choreographer messaging engine, the default is to have a separate
Derby database (BPEME). If you use the Profile Management Tool, you can
also select to use a File Store or to share the WPRCSDB database.
v If you will use the Installer or Profile Management Tool to create a
deployment environment that includes a Business Process Choreographer
configuration, Business Process Choreographer, Business Process
choreographer Observer, and the Business Process Choreographer messaging
engine will all use the WPRCSDB database. Therefore, you do not need to do
any database planning for Business Process Choreographer.
Results
You have planned all the database for your Business Process Choreographer
configuration.

Planning the BPEDB database


Plan the database for Business Process Choreographer.
About this task
Business Process Choreographer requires a database. SQL scripts are provided for
all supported database systems to create and administer the database schema.
Once a database is in place, JDBC access to the database has to be configured for
Business Process Choreographer. Depending on the database system, your
topology, the purpose of the installation, and the administrative tool you choose to
use, some or all of the tasks to create the database and to configure JDBC access
can be automated. For a productions system, Business Process Choreographer

Chapter 3. Planning to configure Business Process Choreographer

117

should have its own database, but if performance is not important, you can also
configure Business Process Choreographer to share a database with other
WebSphere Process Server components.
Procedure
1. Make sure that your choice of BPEDB database and configuration path are
compatible: The following databases are supported:
v DB2 UDB for Linux, UNIX, and Windows
v DB2 for iSeries
v DB2 for z/OS
v Derby
v Informix Dynamic Server
v Microsoft SQL Server
v Oracle
If you have already decided how you are going to configure Business Process
Choreographer, your choice of configuration path has implications on how
you can create the database. If you have not yet decided which configuration
path to use to configure Business Process Choreographer, identifying your
database requirements will help eliminate the configuration paths that do not
support your needs. For details about which databases are supported by each
configuration path, see Table 4 on page 97.
2. If you want a simple database setup with minimum planning and the
following characteristics:
v It does not offer the performance, scalability, nor security that is normally
required for a production system.
v All database objects are created in a single table space, for example the
default tablespace.
v The database server is local to the WebSphere Process Server machine.
v The user ID used to access the database also has administration rights.
The options that you need to plan depend on the configuration path that you
choose:
v If you use the Installer or Profile Management Tool to get a sample
Business Process Choreographer configuration, a separate Derby BPEDB
database is created for Business Process Choreographer, which requires no
further planning.
v If you use the administrative consoles Deployment Environment wizard to
configure Business Process Choreographer, plan to use a copy of the
provided SQL script to create the BPEDB database, which will create the
default schema in a single table space.
v The bpeconfig.jacl tool can configure Business Process Choreographer and
the JDBC access for any database.
If you will run the bpeconfig.jacl script in interactive mode, you can
select to create the tables in an existing database.
If you have a user ID with the authority to create the database objects,
you can use the -createDB yes option, which causes the bpeconfig.jacl
script to generate and run an SQL file to create the database objects in
the default table space. In this case also plan to stop the server and use
the -conntype NONE option for the wsadmin utility. If you are using an
Oracle database, the database must already exist. If you are using a DB2
for z/OS database, the database instance must already exist. For other
database types, bepconfig.jacl will try to create the database instance. If

118

Business Process Choreographer

any error occurs while creating the database or objects, you can use the
generated SQL scripts as if you used the -createDB no option.
If you do not have a user ID with the authority to create the database
objects, you must use the -createDB no option, which causes the
bpeconfig.jacl script to generate an SQL file to create the database objects
in the default table space, but it does not run the script. In this case, plan
to ask your database administrator to customize and run the script for
you.
For more information about the tool and other database parameters, see
bpeconfig.jacl script file on page 157.
v Using the administrative consoles Business Process Choreographer
configuration page:
To have the Business Process Choreographer database objects created in
the common database, plan to use the default database as the target for
the Business Process Choreographer data source.
To reuse an existing database, plan to specify the existing database
instance as the target for the Business Process Choreographer data
source.
If you select the Create tables option, Business Process Choreographer
will create the database objects that it needs in the default table space,
the first time that it uses the database. This option cannot be used for a
DB2 on z/OS database nor for a remote Oracle database.
To create the database using scripts, plan not to use the Create tables
option.
3. If you want a high performance database setup for Business Process
Choreographer with the following characteristics:
v The database is only used by Business Process Choreographer.
v Ideally, the database server is on a dedicated machine, however it can also
be local to the WebSphere Process Server machine.
v You can customize the allocation of tables space to disks for better
performance.
v You can use a different user ID to access the database to the one used to
administer it.
You must plan all the following steps:
4. If you have not already planned the user IDs for the database, perform Table 8
on page 113.
5. Plan the allocation of disks and table spaces. Ideally, the database host should
have a fast storage subsystem, such as network-attached storage or a storage
area network. For a production system, take into account the results of your
experiences during development and system testing. The size of your database
depends on many factors. Processes that run as microflows use very little
space, yet each process template can require tens or hundreds of kilobytes.
If you will use individual disks, and your database system supports allocating
database tables to different disks, plan how many disks you will use and how
you will allocate them. Hardware-assisted disk arrays usually offer better
performance than single disks.If you use one of the following:
v DB2
v DB2zOSV8
v DB2zOSV9
v Informix (table spaces are known as named dbspaces)
Chapter 3. Planning to configure Business Process Choreographer

119

v Oracle
Plan where to locate the following BPEDB database table spaces:
v The AUDITLOG table space stores audit events mainly for backward
compatibility. It is not used much.
v The COMP table space is required for deprecated compensation, it is only
maintained for backward compatibility. It is not used.
v The INDEXTS table space stores indexes. It is used intensively and its growth
rate correlates with the number of instances.
v The INSTANCE table space stores instance data for instances of business
processes and human tasks. It is used intensively and its growth rate
depends on your business applications.
v The LOBTS table space stores large data objects of instances of business
processes and human tasks. It is used intensively and its growth rate
correlates with the number of instances.
v The SCHEDTS table space stores scheduler information related to business
processes and human tasks. It is used frequently and its growth rate
correlates to the number of instances.
v The STAFFQRY table space stores authorization data for business process. It is
used frequently and its growth rate depends on how you have modelled
authorization.
v The TEMPLATE table space stores template information. It is used frequently
and its growth rate correlates to the number and size of installed business
process and human task applications.
v The WORKITEM table space stores authorization data for business process and
human tasks. It is used intensively, and its growth rate correlates with the
number of instances.
They can be all on one high-performance RAID-array, but each table space
should be in a different file to allow parallel access. Keep in mind that for a
given number of disks, using a RAID configuration will have better
performance than allocating table spaces to separate disks. For example, for a
DB2 database that is running on a dedicated server with N processors,
consider using the following guidelines:
v For the table spaces, use a RAID-1 array with 2*N primary disks, 2*N
mirror disks, and a stripe size of 256 kb.
v For the database transaction log, use a RAID-1 array with 1.5*N primary
disks, 1.5*N mirror disks, and a stripe size of 64 kb.
If you are using a DB2 database, running on a four-processor server, and will
use 15 disk drives on a RAID controller, consider using the following
allocations:
v One disk for the operating system and paging (known as the page file on
Windows, paging space on AIX and HP-UX, and swap space on Solaris).
v Use eight disks in a RAID-1 configuration (four primary disks and four
mirrors) as one logical disk for the database control files and table spaces,
using a stripe size of 256 kB.
v Use six disks in a RAID-1 configuration (three primary disks and three
mirrors) as one logical disk for the database transaction log, using a stripe
size of 64 kB.
If you are using an Oracle database, consider the following guidelines:
v Stripe and mirror everything (SAME) for all files, across all disks, using a
one megabyte stripe width.

120

Business Process Choreographer

v Mirror data for high availability.


v Create a partition (for the tables space) that is on the outside half of the
disk drives.
v Subset data by partition, not by disk.
v Use the Automatic Storage Management (ASM) file system.
v Do not separate redo logs from other data files.
6. Plan that you or your database administrator will customize the SQL scripts
that create the database objects before running them.
v If you use the bpeconfig.jacl tool to configure Business Process
Choreographer, use the -createDB no option. This prevents the tool from
running the SQL script that it generates. The generated SQL files are based
on the original SQL files that are provided for your database, but with all
configuration parameters that are provided to the bpeconfig.jacl tool
pre-filled in the SQL file, which minimizes the customization necessary.
v If you use the administrative consoles Business Process Choreographer
configuration page or Deployment Environment wizard to configure
Business Process Choreographer, plan to clear the Create tables option, to
make sure that you do not get the default schema. The generated SQL files
are based on the original SQL files that are provided for your database, but
all configuration parameters that you enter in the administrative console are
pre-filled in the generated SQL file, which minimizes the customization
necessary.
For more information about using the generated SQL scripts, refer to Using a
generated SQL script to create the database schema for Business Process
Choreographer on page 176. If you want to preview the original SQL files for
your database, so that you can plan what customizations you will make,
locate and view the SQL createSchema.sql script for your database, but do not
modify it. The original SQL files are located in the following directory:
v On Windows platforms: install_root\dbscripts\ProcessChoreographer\
database_type
v On Linux, UNIX, i5/OS, and in the UNIX System Services (USS) on z/OS
platforms: install_root/dbscripts/ProcessChoreographer/database_type
Where database_type is one of the following:
v DB2
v DB2zOSV8
v DB2zOSV9
v Db2iSeries
v Derby
v Informix
v Oracle
v SQLServer
7. If the database server is remote to the process server, plan to install either a
Java Database Connectivity (JDBC) driver or a database client on the process
server machine:
v For a Type 2 JDBC driver: Decide which database client to install, and
where to install it.
v For a Type 4 JDBC driver: Locate the JAR file for the driver, which is
provided as part of your product installation, and decide where to install it.
8. If the database server is local to the process server, the JDBC JAR files
required to access the database are installed with the database system. Find
and note the location of these JAR files.

Chapter 3. Planning to configure Business Process Choreographer

121

9. If you use DB2 for z/OS, decide on the subsystem to use. Plan the values that
you will substitute for storage group name, database name (not the subsystem
name), and schema qualifier in the script files createTablespace.sql and
createSchema.sql.
10. Decide which server will host the database. If the database server is remote,
you need a suitable database client or a type-4 JDBC driver that has
XA-support.
11. Decide the values for the following configuration parameters that you will
need to specify for the database:
v The Java Database Connectivity (JDBC) provider can be type-2 or type-4.
For Oracle, decide between using the oci or thin driver.
v Database instance (for Oracle, the database name, for DB2 on z/OS: the
subsystem name).
v Schema qualifier. The default is to use the connection user ID as the implicit
schema qualifier.
v User name to create the schema.
v If you are using a type-4 JDBC driver: the name or IP address of the
database server.
v The port number used by the database server. This is only required if you
are using a type-4 JDBC driver.
v The user ID and password for the authentication alias. This is the user ID
that the jdbc/BPEDB data source uses to access the database at runtime.
These are the -dbUser and -dbPwd parameters for bpeconfig.jacl.
12. Plan to support enough parallel JDBC connections:
a. Estimate the maximum number of parallel JDBC connection required to
the Business Process Choreographer BPEDB database. This will depend on
the nature of your business processes and the number of users. A good
estimate is the maximum number of clients that can concurrently connect
through the Business Process Choreographer API plus the number of
concurrent endpoints defined in the BPEInternalActivationSpec and
HTMInternalActivationSpec JMS activation specifications, plus a 10%
safety margin to allow for overload situations.
b. Make sure that your database system can support the necessary number of
parallel JDBC connections.
c. Plan suitable settings according to the best practices for your database
system to support the expected number of parallel JDBC connections.
13. For a production system, make plans for the following administration tasks:
v Tune your database after it is populated with typical production data.
v Regularly delete completed process instances and task instances from the
database.
Results
You have planned the database for Business Process Choreographer.
Related tasks
Balancing the hardware resources on page 584
You can improve the performance of long-running business processes by
balancing the hardware resources.

122

Business Process Choreographer

Planning the OBSRVRDB database


Plan the database for the Business Process Choreographer Observer.
About this task
Business Process Choreographer Observer can use the same database, but using an
additional database, OBSRVRDB, gives better performance. If you will not reuse
the BPEDB database, perform the following:
Procedure
1. If you plan to have multiple event collector instances, and they are going to
use the same database, plan unique schema names for each event collector.
For better performance, plan a database for each event collector.
2. Decide which database system to use for the database:
v Derby
v DB2 UDB for Linux, UNIX, and Windows
v DB2 for iSeries
v DB2 for z/OS
v Oracle
Restriction: The Business Process Choreographer Observer does not support
using an Informix or SQL Server database.
3. Decide which server will host the database.
4. If you have not already planned the user IDs for the database, perform Table 9
on page 113.
5. If you will not use the bpeconfig.jacl script to configure the observer and
event collector to use the BPEDB database, decide how you will create the
OBSRVRDB database.
Using the menu-driven administration tool, setupEventCollector
You can use this tool to create the database in an interactive mode,
with your input validated against the runtime environment. If you use
this tool, decide whether you want the tool to create an SQL file, but
not run it use this option if you want to customize the SQL before
running it or to give to your database administrator to customize and
run. For more information about this tool, see setupEventCollector
tool on page 258.
The tool allows you to create either Java-based user-defined functions
(UDFs) or SQL-based UDFs, and to switch between these two options,
and also to install and remove the JAR file that is required to support
the UDFs. For a non-Derby database, the tool supports creating the
database using either Java-based user defined functions (UDFs) or
SQL-based UDFs.For a DB2 on z/OS database, the tool supports
creating the database using either Java-based UDFs or SQL-based
UDFs. For a Derby database, only Java-based UDFs are used to create
the database.
Running SQL scripts
You might need to use the SQL scripts if you are not allowed to use a
tool to access the database. If you configured Business Process
Choreographer using the bpeconfig.jacl script in batch mode or using
the administrative console, an SQL script is generated that has all
necessary parameters substituted. Otherwise, you can use the standard
SQL scripts which must be customized.

Chapter 3. Planning to configure Business Process Choreographer

123

For a non-Derby database, all SQL scripts create the UDFs for the
Business Process Choreographer Observer using the SQL
implementation, which simplifies the task when configuring using the
SQL based UDFs. . For a Derby database, only Java-based UDFs are
used to create the database.
Automatically create tables on first use
Selecting the Create tables option on the administrative consoles
Business Process Choreographer configuration page is an easy way to
get a default database schema. This option is not suitable for high
performance systems. For a non-Derby database, SQL-based UDFs are
used, which simplifies the configuration task. This option cannot be
used for a DB2 on z/OS database. For a Derby database, only
Java-based UDFs are used to create the database.
Note:
v If you use a DB2 for z/OS database, and would prefer that the database is
created using Java-based UDFs, rather than SQL-based UDFs, then you
have no choice but to use the menu-driven administration tool,
setupEventCollector.
v If you use a Derby database, Java-based UDFs will be used because the
embedded Derby database does not support SQL UDFs.
For more information about UDFs, see User-defined functions for Business
Process Choreographer Observer on page 240.
6. If you use a DB2 for Linux, UNIX, or Windows database, plan the following:
v The database name. The default value is BPEDB.
v The user ID to use to connect to the database. You must also know the
password for this user ID.
v The database schema name to use to create the database objects. The default
value is the connection user ID.
v Plan the fully qualified location for the table space OBSVRTS.
v Decide whether you want to use the SQL-based user-defined function
(UDFs) rather than the default, Java-based ones.
v If you will use the setupEventCollector tool to setup the database, also plan
the following:
Decide which type of JDBC driver to use:
- Type 2, connecting using a native database client. This is the default.
- Type 4, connecting directly via JDBC. In this case, also make sure that
you know the following:
v The hostname or IP address of the database server. The default is
localhost.
v The port number used for the database. The default is 50000.
Locate the directory where the DB2 JDBC driver files, db2jcc.jar and
db2jcc_license_cu.jar are installed.
7. If you use a DB2 for i5/OS database, plan the following:
v The database name. If you configure the database in the native i/Series
environment, for example, in qshell, use *LOCAL. Otherwise, use *SYSBAS.
v The user ID to use to connect to the database. You must also know the
password for this user ID.
v The database schema name, under which, the database objects are created.
The default value is the connection user ID.

124

Business Process Choreographer

v Decide whether you want to use the SQL-based user-defined function


(UDFs) rather than the default, Java-based ones.
v If you will use the setupEventCollector tool to setup the database, also plan
the following:
The hostname of the database server. Typically this is always localhost.
The port number is always 446.
The directory for the JDBC driver:
- If the database is in a native i/Series environment, for example, in
qshell, this is the path where the db2_classes.jar file is located, which
is normally /QIBM/ProdData/Java400/ext.
- If the database is remote, this is the path where the jt400.jar file is
located.
8. If
v
v
v

you use a DB2 for z/OS database, plan the following:


Location name (network name) of the subsystem.
The storage group name.
The database name as known by the subsystem. The default value is
OBSRVRDB
v The user ID to use to connect to the database. You must also know the
password for this user ID.
v The database schema name (SQLID), under which, the database objects are
created.
v Plan in which storage group the table spaces will be created:
Regular table space for OBSVR01, OBSVR02, OBSVR03, OBSVR04,
OBSVR05, OBSVR06, OBSVR07, and OBSVR08.

9. If
v
v

LOB table space for OS26201, OS26202, OS26203, and OS26204.


If you want to use the Java-based user-defined function (UDFs) rather than
the default SQL ones, decide on the name of the WLM environment that
you will use to run the functions in.
If you will use the setupEventCollector tool to setup the database, also plan
the following:
Decide which type of JDBC driver to use:
- Type 4, connecting directly via JDBC. In this case, also make sure that
you know the following:
v The hostname or IP address of the database server. The default is
localhost.
v The port number used for the database. The default is 446.
v The directory for the JDBC driver JAR files, db2jcc.jar and
db2jcc_license_cisuz.jar.
- Type 2, connecting using a native database client. In this case, also
plan what the database alias will be in the local catalog.
you use a Derby database, plan the following:
The database name. This must be the fully qualified path on the servers file
system. The default value is install_root/databases/BPEDB.
The database schema name, under which, the database objects are created.
The default value is APP.

v If you will use the setupEventCollector tool to setup the database, also plan
the following:

Chapter 3. Planning to configure Business Process Choreographer

125

If you use the Derby Network JDBC driver, plan the user ID to use to
connect to the database. You must also know the password for this user
ID.
Decide which type of JDBC driver to use:
- Embedded JDBC driver. In this case, also plan the directory for the
JDBC driver JAR file derby.jar. The default location is
install_root/derby/lib.
- Network JDBC driver. In this case, also make sure that you know the
following:
v The directory for the JDBC driver JAR file derbyclient.jar. The
default location is install_root/derby/lib.
v If using a Derby Network server, decide on the location of the UDF
JAR file bpcodbutil.jar on the Derby network server. The default
location is install_root/derby/lib.
v The hostname of the database server. The default is localhost.
v The port number used for the database. The default is 1527.
10. If you use an Oracle database, plan the following:
v The SID name. The default value is BPEDB.
v Decide which Oracle user ID to use to connect to the database. It must have
the roles CONNECT and RESOURCE. The default user ID is system . You
must also know the password for this user ID.
v The database schema name, under which, the database objects are created.
The default value is the user ID used to connect to the database.
v Plan the fully qualified locations for each of the following table spaces:
OBSVRIDX
OBSVRLOB
OBSVRTS
v Decide whether you want to use the SQL-based user-defined function
(UDFs) rather than the default, Java-based ones.
v If you will use the setupEventCollector tool to setup the database, also plan
the following:
The location of the JDBC driver file. For Oracle 10g use the ojdbc14.jar
driver. For Oracle 11g use the ojdbc5.jar driver.
The hostname of the database server. The default is localhost.
The port number used for the database. The default is 1521.
11. If you use the bpeconfig.jacl tool in batch mode with the
-createEventCollector yes option, plan one of the following:
v The -createDB yes option causes the tool to run the SQL script that
bpeconfig.jacl generates. You can use the -dbSchema parameter to specify a
schema qualifier for the BPEDB database, but the Business Process
Choreographer Observer will use the same schema in the same database.
That is why using the -createDB yes option is not suitable for a
high-performance system.
v The -createDB no option prevents the tool from running the SQL script that
it generates. The generated SQL files are based on the standard SQL files
that are provided for your database, but with all configuration parameters
that are provided to the bpeconfig.jacl tool pre-filled in the SQL file, which
minimizes the customization necessary. Plan that you or your database
administrator will customize the generated SQL script that creates the
database objects before running it. For more information about the tool and

126

Business Process Choreographer

other database parameters, see Using the bpeconfig.jacl script to configure


Business Process Choreographer on page 150.
Restriction: You cannot configure the Business Process Choreographer
Observer using the bpeconfig.jacl script in interactive mode.
12. If you will use administrative consoles Business Process Choreographer
event collector page to create the database tables, plan one of the following:
v For all database types except for DB2 on z/OS, you can use the Create
tables option to cause the tool to create the default schema in the specified
database the first time that Business Process Choreographer accesses the
database.
v If you want to run an SQL script to prepare the database tables, do not use
the Create tables option. Plan that you or your database administrator will
customize a copy of the SQL script that creates the database objects before
running it. This option is most suitable for a production system.
13. If you want to preview the SQL script for your database, so that you can plan
what customizations you will make: Locate and view the
createSchema_Observer.sql file for your database, but do not modify it. The
SQL files are located in:
v On Windows platforms: install_root\dbscripts\ProcessChoreographer\
database_type
v On Linux, UNIX, i5/OS, and in the UNIX System Services (USS) on z/OS
platforms: install_root/dbscripts/ProcessChoreographer/database_type
Where database_type is one of the following:
v DB2
v DB2zOSV8
v DB2zOSV9
v Db2iSeries
v Derby
v Oracle
Note: If you use the bpeconfig.jacl tool to configure Business Process
Choreographer, plan to use the SQL script that the tool generates, which does
not need to be edited to substitute values for placeholders for configuration
parameters. The generated scripts are only available after running the tool, but
they are based on the scripts in the locations listed above. You will still have
to edit the generated script file if you want to customize the table space
allocations.
Results
You have planned the database for the Business Process Choreographer Observer.

Planning the messaging engine database


For high-load setups, where database logging might become a bottleneck, you can
improve performance by using a separate database for the messaging engine for
the Business Process Choreographer bus.
About this task
You can use the same messaging database for each messaging engine for the
Service Component Architecture (SCA) system bus, each messaging engine for the
SCA application bus, each messaging engine for the Common Event Infrastructure
bus, and each messaging engine for the Business Process Choreographer bus. The
database should be accessible to all members of the cluster that hosts the message
Chapter 3. Planning to configure Business Process Choreographer

127

engine to ensure failover availability of the message engine. If performance is


important, plan to use a dedicated database for the Business Process
Choreographer messaging engine, rather than using the default MEDB that is used
for the SCA bus and applications.
Procedure
1. If you use the Installer or Profile Management Tool to get one of the sample
Business Process Choreographer configurations, decide whether the Business
Process Choreographer messaging engine will use Derby embedded, file store,
or the WPRCSDB database.
2. The Java Database Connectivity (JDBC) provider. Note that the file store and
embedded Derby database are not available in a network deployment
environment.
3. If you want to use WebSphere MQ, you must use the bpeconfig.jacl
configuration script to configure Business Process Choreographer. Using
WebSphere MQ is deprecated.
4. If you use the bpeconfig.jacl configuration script to configure Business Process
Choreographer on a stand-alone server, decide what you will use for the
message store:
v A separate schema in the messaging engine database for SCA.
v A separate Derby database.
v Any user-defined data source that has been created on the deployment target
before running the bpeconfig.jacl script.
v A file store.
5. If you use the administrative consoles Business Process Choreographer
configuration page, plan the following configuration parameters.
v Local or remote bus member location.
v The name of the database. The default is BPEME.
v The schema name. The default is MEDBPM00.
6. If you are using a file store or the embedded Derby JDBC provider, the
message stores will be created automatically.
7. If you are not using a file store or the embedded Derby JDBC provider, plan
the following configuration parameters.
a. Plan that the database will already exist before Business Process
Choreographer is started.
b. The host name or IP address of the database server, and the port number
that it uses.
c. The user name used to connect to the database and to create the schema.
This is the user ID that you planned in Table 10 on page 114.
Results
You have planned the database for the Business Process Choreographer messaging
engine.

Planning for the Business Flow Manager and Human Task


Manager
The core of a Business Process Choreographer configuration consists of the
Business Flow Manager and the Human Task Manager. You must plan their
configuration parameters.

128

Business Process Choreographer

Procedure
1. Make sure you know the Java Message Service (JMS) provider user ID that will
be used as the run-as user ID for the Business Flow Manager message driven
bean. In the administrative console, and in Table 11 on page 114, it is known as
the JMS API Authentication User.
2. Make sure you know the Java Message Service (JMS) provider user ID that will
be used as the run-as user ID for the Human Task Manager message driven
bean. In the administrative console, and in Table 11 on page 114, it is known as
the Escalation User Authentication User.
3. Make sure you know which groups or user IDs the security roles for
administrator and monitor will map onto. For details, see Table 12 on page 115.
4. If you want the Human Task Manager to send e-mail notifications of escalation
events , identify the host name or IP address where the Simple Mail Transfer
Protocol (SMTP) e-mail server is located. Plan what the sender address should
be for email notifications. If the e-mail service requires authentication, make
sure you know the user ID and password to use to connect to the service.
5. Decide on the context root for the Web service binding of the API.
v When configured on a server:
The default for the Business Flow Manager is
/BFMIF_nodeName_serverName.
The default for the Human Task Manager is
/HTMIF_nodeName_serverName
v When configured on a cluster:
The default for the Business Flow Manager is /BFMIF_clusterName
The default for the Human Task Manager is /HTMIF_clusterName
6. If you are going to use the Business Process Choreographer Explorer, the
Business Space, or a client that uses the Representational State Transfer (REST)
API, decide on the context root for the REST API. The default for the Business
Flow Manager is /rest/bpm/bfm. The default for the Human Task Manager is
/rest/bpm/htm.
v When configured on a server, or on a single cluster, or on multiple clusters
that are mapped to different Web servers, you can use the default values.
v When configured in a network deployment environment on multiple
deployment targets that are mapped to the same Web server, do not use the
default values. The context root for each Business Process Choreographer
configuration must be unique for each combination of host name and port.
You will have to set these values manually using the administrative console
after configuring Business Process Choreographer.
7. Decide whether you want to initially enable audit logging for the Business
Flow Manager, or Human Task Manager, or both.
8. If you are going to use the Business Process Choreographer Observer, decide
whether you want the Business Flow Manager to be initially configured to
generate Common Event Infrastructure logging events.
Results
You have planned all the initial configuration parameters for the Business Flow
Manager and Human Task Manager. You can change any of these setting anytime
later using the administrative console.

Chapter 3. Planning to configure Business Process Choreographer

129

Planning for the people directory provider


Plan the people directory provider, people substitution, virtual member manager,
and Lightweight Directory Access Protocol (LDAP) settings for Business Process
Choreographer.
Procedure
1. If you are going to use human tasks, decide which people directory providers
you will use:
Virtual member manager (VMM) people directory provider
The VMM people directory provider is ready to use federated
repositories (also known as virtual member manager) as is
preconfigured for WebSphere security using a file repository. If you
want to use a different user repository with federated repositories, you
will need to reconfigure federated repositories. The VMM people
directory provider supports all Business Process Choreographer people
assignment features including substitution. It relies on the features
provided by federated repositories, such as support for different
repository types, such as LDAP, database, file based, and property
extension repository.
To use the VMM people directory provider requires that you have
configured federated repositories for WebSphere Application Server
security. You can associate federated repositories with one or more user
repositories, based on a file, LDAP, or a database. For more information
about this, see Managing the realm in a federated repository
configuration. For more information about using federated repositories,
see IBM WebSphere Developer Technical Journal.
Lightweight Directory Access Protocol (LDAP) people directory provider
This people directory provider must be configured before you can use
it. Perform the planning in step 2.
System people directory provider
This people directory provider can be used without configuring it. Do
not use this provider for a production system, it is only intended for
application development testing.
User registry people directory provider
This people directory provider can be used without configuring it.
Depending on the WebSphere security realm definition, the user
registry can use one of the following repositories:
v Federated repository which can use the following:
File registry
One or more LDAPs
One or more databases
v Standalone LDAP
v Standalone custom
v Local operating system
2. If you are going to use the Lightweight Directory Access Protocol (LDAP), plan
the following.
a. You might need to customize your own version of the
LDAPTransformation.xsl file. For the location of that file and a list of
properties that you might need to customize, see Configuring the LDAP
people directory provider on page 194.

130

Business Process Choreographer

b. Plan the following LDAP custom properties:


LDAP plug-in property

Required or
optional

AuthenticationAlias

Optional

The authentication alias used to connect to LDAP, for example,


mycomputer/My LDAP Alias. You must define this alias in the
administrative console by clicking Security Secure administration,
applications, and infrastructure Java Authentication and
Authorization Service J2C Authentication Data. If this alias is not
set, anonymous logon to the LDAP server is used.

AuthenticationType

Optional

If this property is set to simple, for simple authentication, then the


AuthenticationAlias parameter is required. Otherwise, if it is not set,
anonymous authentication is used.

BaseDN

Required

The base distinguished name (DN) for all LDAP search operations, for
example, o=mycompany, c=us. To specify the directory root, specify an
empty string using two single quotes, .

Casesentiveness
ForObjectclasses

Optional

Determines whether the names of LDAP object classes are


case-sensitive.

ContextFactory

Required

Sets the Java Naming and Directory Interface (JNDI) context factory,
for example, com.sun.jndi.ldap.LdapCtxFactory

ProviderURL

Required

This Web address must point to the LDAP JNDI directory server and
port. The format must be in normal JNDI syntax, for example,
ldap://localhost:389. For SSL connections, use the LDAPs URL.

SearchScope

Required

The default search scope for all search operations. Determines how
deep to search beneath the baseDN property. Specify one of the
following values: objectScope, onelevelScope, or subtreeScope

additionalParameter
Name1-5 and
additionalParameter
Value1-5

Optional

Use these name-value pairs to set up to five arbitrary JNDI properties


for the connection to the LDAP server.

Description

3. If you are going to use the virtual member manager, plan the following.
a. You might need to customize your own version of the
VMMTransformation.xsl file. For the location of that file and a list of
properties that you might need to customize, refer to Configuring the
Virtual Member Manager people directory provider on page 192.
4. If you want to use people substitution, consider the following:
v You must use the VMM people directory provider. The LDAP, system, and
user registry people directory providers do not support people substitution.
v If you are going to use people substitution in a production environment, plan
to use the VMM Property Extension Repository to store the substitution
information. The Property Extension Repository and, implicitly, the selected
database must be unique and accessible from within the whole cell. As the
BPEDB database is not necessarily unique within a cell, BPEDB cannot be
used. You can use the common database, WPSRCDB, to host the Property
Extension Repository, however, for a production environment, it is
recommended to use a database that is independent of other WebSphere
Process Server databases.
v To use people substitution in a single-server test environment, you can store
people substitution information in the internal file registry that is configured
for federated repositories.
Results
Chapter 3. Planning to configure Business Process Choreographer

131

You have planned the people directory provider and people assignment options.

Planning for the Business Process Choreographer Explorer


Plan the configuration parameters for the Business Process Choreographer
Explorer.
About this task
If you will use the Business Process Choreographer Explorer. you can either plan
and configure it at the same time as you configure Business Process
Choreographer, or you can do it later.
Procedure
For the Business Process Choreographer Explorer instance that you want, plan the
following:
v The context root for the Business Process Choreographer Explorer. It must be
unique within the cell. The default is /bpc.
v The URL for the Business Process Choreographer Explorer that will be inserted
in escalation e-mails.
v The URL for the Business flow Manager and Human Task Manager REST APIs.
They must match the value planned for the context roots that you planned for
the REST APIs.
v The maximum number of results to be returned for a query - the default is
10000.
v The deployment target (server or cluster) of the Business Process Choreographer
instance that this Business Process Choreographer Explorer will manage.
Results
You have planned the configuration options for the Business Process
Choreographer Explorer.

Planning for the Business Process Choreographer Observer


Plan to configure the Business Process Choreographer Observer and event collector.
About this task
If you will use the Business Process Choreographer Observer, you can either plan
and configure it at the same time as you configure Business Process
Choreographer, or you can do it later.
Procedure
1. Understand the purpose and relationships between the different Business
Process Choreographer Observer topology elements.
The observer application.
You can configure multiple instances on a server or cluster. The
instances do not need to be on a deployment target where Business
Process Choreographer has been configured. Each instance connects via
a data source to exactly one database schema.
The event collector application.
This application must be deployed on a server or cluster where the

132

Business Process Choreographer

Common Event Infrastructure (CEI) server is configured. It does not


need to be deployed where Business Process Choreographer has been
configured. It receives business process events from CEI, transforms
them, and writes them to the OBSRVRDB database.
The OBSRVRDB database.
The event collector and observer communicate by using the same
database. For non-production systems, the database can be shared with
other components.
Your choices are independent of the topology you have for your Business
Process Choreographer setup. For more insight into the possibilities, see About
Business Process Choreographer Observer on page 137.
2. Identify the purpose of your setup, your machine requirements, and the
topology implications.
Simple setup
For simpler configuration and administration, but lower performance,
deploy the observer and event collector applications on the same
deployment target as you have Business Process Choreographer and
CEI configured on, and use a local database system.
High load production system: network deployment
Use a cell of multiple nodes, with multiple clusters. Install instances of
the observer application on any deployment targets in the cell. Install
the event collector application on the cluster where you have
configured the Common Event Infrastructure (CEI). Use a separate
database server.
3. If you have not already planned the database for the observer, perform
Planning the OBSRVRDB database on page 123.
4. For each event collector instance that you want to configure, plan the following:
a. Decide where you will install it. You can only install one event collector
instance per deployment target, and the deployment target must have CEI
configured on it.
b. Decide how you will configure this event collector instance:
v Using the administrative console page. For more information about this
option, see Using the administrative console to configure a Business
Process Choreographer event collector on page 248.
v Using the interactive setupEventCollector tool. For more information
about this option, see Using the setupEventCollector tool to configure a
Business Process Choreographer event collector on page 246.
v At the same time as creating a Business Process Choreographer
configuration, using the bpeconfig.jacl script. The -createEventCollector
option has the default value yes.
Note: Do not use bpeconfig.jacl to configure the Business Process
Choreographer Observer for a high-performance system, because
bpeconfig.jacl will configure the event collector and observer applications
on the same deployment target as the Business Process Choreographer
configuration, and configure them to share the BPEDB database. For more
information about this option, see Using the bpeconfig.jacl script to
configure Business Process Choreographer on page 150.
You cannot use bpeconfig.jacl to configure the Business Process
Choreographer Observer in interactive mode.
c. Plan the data source:
Chapter 3. Planning to configure Business Process Choreographer

133

v If security is important:
If the Business Process Choreographer Observer shares the same
physical database as Business Process Choreographer, plan to use a
separate data source for the observer database, and plan its JNDI
name.
Plan an authentication alias that will be used for the database.
v If security is unimportant:
If the Business Process Choreographer Observer shares the same
physical database as Business Process Choreographer (BPEDB), you
can use the same data source, and therefore the same JNDI name.
If you use the same data source, you will also use the same
authentication alias.
v Plan to create the data source with a cell scope.
d. Plan the configuration parameters required when configuring the event
collector:
v The JNDI data source name for the database.
v The schema to be used for the database objects. The default is the user ID
that is used to connect to the database.
v The user ID to use to connect to the database. The default depends on the
database: For DB2 the default is db2admin, for Oracle the default is
system, and for other databases the default is the user ID of the logged
on user.
v The password for the user ID.
v If you are using a type 4 JDBC connection, also collect the host name or
IP address of the database server and the port number that it uses
v Decide where the event collector will be deployed. The deployment target
must have CEI configured on it, so if you have a separate cluster for CEI,
plan to deploy the event collector on the same cluster.
v If you will deploy the event collector in a network deployment
environment, know on which deployment target the messaging engine
for the CEI bus is configured.
v If the CEI bus has security enabled, plan the JMS user ID that will be
used to authenticate with the CEI bus.
v Decide whether you want to enable CEI event logging business events
when configuring the event collector, or whether you will enable it later
using the administrative console or by running a script.
e. Plan the runtime configuration values, which you might need to customize
to suit your needs after configuring the event collector:
v BpcEventTransformerEventCount
v BpcEventTransformerMaxWaitTime
v BpcEventTransformerToleranceTime
v ObserverCreateTables
v If the authentication alias user ID will not own the database schema, plan
the ObserverSchemaName.
For more information about these values, see Changing configuration
parameters for the Business Process Choreographer Observer on page 253.
5. For each Business Process Choreographer Observer instance that you configure,
plan the following:
v Decide how you will configure this instance:

134

Business Process Choreographer

Using the administrative console page. For more information about this
option, see Using the administrative console to configure a Business
Process Choreographer Observer on page 250.
Using the interactive setupObserver tool. For more information about this
option, see Using the setupObserver tool to configure a Business Process
Choreographer Observer on page 249.
At the same time as creating a Business Process Choreographer
configuration, using the bpeconfig.jacl script. The -createObserver option
has the default value yes.
Note: Do not use bpeconfig.jacl to configure the Business Process
Choreographer Observer for a high-performance system, because
bpeconfig.jacl will configure the event collector and observer applications
on the same deployment target as the Business Process Choreographer
configuration, and configure them to share the BPEDB database. For more
information about this option, see Using the bpeconfig.jacl script to
configure Business Process Choreographer on page 150.
v The deployment target for this instance.
v The JNDI name for the data source that is used by the event collector that
this instance will monitor.
v If you will use the administrative console to configure this instance, also plan
the following:
The context root for this instance. This specifies part of the URL that is
used in a browser to reach this Business Process Choreographer Observer
instance. The default is /bpcobserver.
The deployment target of the event collector instance whose data will be
visualized by this Business Process Choreographer Observer instance.
6. If you will use the bpeconfig.jacl script to configure Business Process
Choreographer:
v When the script is run in batch mode, the default is that it will also configure
the event collector and observer applications, and that they will be
configured on the same deployment target as the Business Process
Choreographer configuration.
v If you do not want bpeconfig.jacl to configure one or both of the event
collector and observer applications, plan to use one or both of the
bpeconfig.jacl options -createEventCollector no and -createObserver no,
which prevent bpeconfig.jacl from configuring them.
Results
You have planned the configuration options for the Business Process
Choreographer Observer and event collector.

About Business Process Choreographer


Describes the facilities provided by the Business Flow Manager and the Human
Task Manager.
Business Process Choreographer is an enterprise workflow engine that supports
both business processes and human tasks in a WebSphere Application Server
environment. These constructs can be used to orchestrate services as well as
integrate activities that involve people in business processes. Business Process

Chapter 3. Planning to configure Business Process Choreographer

135

Choreographer manages the life cycle of business processes and human tasks,
navigates through the associated model, and invokes the appropriate services.
Business Process Choreographer provides the following facilities:
v Support for business processes and human tasks. Business processes offer the
standard way to model your business process using the Web Services Business
Process Execution Language (WS-BPEL, abbreviated to BPEL). With human
tasks, you can use the Task Execution Language (TEL) to model activities that
involve people. Both business processes and human tasks are exposed as
services in a Service Oriented Architecture (SOA) or Service Component
Architecture (SCA); they also support simple data objects and business objects.
v Application programming interfaces for developing customized applications for
interacting with business processes and human tasks.
v Business Process Choreographer Explorer. This Web application offers functions
for managing and administering business process and human tasks. For more
information refer to About Business Process Choreographer Explorer.
v Business Process Choreographer Observer. This Web applications allows you to
observe the states of running business processes. For more information refer to
About Business Process Choreographer Observer on page 137.
Related tasks
Planning to configure Business Process Choreographer
Plan your Business Process Choreographer setup and configuration parameters.

About Business Process Choreographer Explorer


Business Process Choreographer Explorer is a Web application that implements a
generic Web user interface for interacting with business processes and human
tasks.
You can configure one or more Business Process Choreographer Explorer instances
on a server or cluster. It is sufficient to have a WebSphere Process Server
installation with a WebSphere Process Server profile, or a WebSphere Process
Server client installation it is not necessary to have Business Process
Choreographer configured on the server or cluster. The WebSphere Process Server
client installation is only the infrastructure that you need to connect a client to a
WebSphere Process Server, it does not contain the Business Process Choreographer
Explorer. Use the deployment manager to install the Business Process
Choreographer Explorer on the servers in the WebSphere Process Server client
installation as well.
A single Business Process Choreographer Explorer can only connect to one
Business Process Choreographer configuration, though it does not have to connect
to a local configuration. However, you can configure multiple instances of the
Business Process Choreographer Explorer on the same server or cluster, and each
instance can connect to different Business Process Choreographer configurations.
When you start Business Process Choreographer Explorer, the objects that you see
in the user interface and the actions that you can take depend on the user group
that you belong to and the authorization granted to that group. For example, if
you are a business process administrator, you are responsible for the smooth
operation of deployed business processes. You can view information about process
and task templates, process instances, task instances, and their associated objects.
You can also act on these objects; for example, you can start new process instances,
create and start tasks, repair and restart failed activities, manage work items, and

136

Business Process Choreographer

delete completed process instances and task instances. However, if you are a user,
you can view and act on only those tasks that have been assigned to you.

About Business Process Choreographer Observer


About Business Process Choreographer Observer.
You can use Business Process Choreographer Observer to create reports on
processes that have been completed. You can also use it to view the status of
running processes. This describes the architecture and possible configuration paths.
Business Process Choreographer Observer uses the Common Event Infrastructure
(CEI) to collect events that are emitted by WebSphere Process Server. You can
either use a number of predefined reports or define your own reports to get an
overview of the number of processes, activities, or other aggregate data. You can
also get information about specific processes or activities.
Business Process Choreographer Observer is based on two J2EE enterprise
applications, which are shown in the following figure:

Business Process
Choreographer

Common Event Infrastructure

Event collector application


(includes the Transformer)

Cleanup
utility

Observer GUI
(browser)

Observer
application

Observer
database

Figure 1. Business Process Choreographer Observer architecture

v The event collector application reads event information from the CEI bus and
stores it in the event collector table in the Business Process Choreographer
Observer database.
v The observer database is a set of database tables that store the event data.
v Periodically the event transformer is triggered, which transforms the raw event
data into a format that is suitable for queries from the Business Process
Choreographer Observer.
v The observer application generates the reports and performs other actions that
the user can initiate using the observer graphical user interface (GUI).
v You can use the GUI to generate your reports. You can also store and retrieve
reports that you have defined.
v A cleanup utility can be used to remove records from the observer database,
which can help to improve the performance.
Chapter 3. Planning to configure Business Process Choreographer

137

Simple configurations
A simple configuration, where performance is not an important consideration is
illustrated in the following figure.

Observer GUI
(browser)
WebSphere Process Server
Business Process
Choreographer
(process and human
task containers)

CEI Event Server


Event collector application
(includes the transformer)

Observer
application

Business Process
Choreographer
database
Figure 2. Business Process Choreographer Observer standalone setup

Everything is installed on a single machine, and Business Process Choreographer


and Business Process Choreographer Observer use the same database.
This kind of simple configuration is created if you create a sample Business Process
Choreographer configuration. Also the bpeconfig.jacl tool defaults to configuring
the observer and event collector applications on the same deployment target as the
Business Process Choreographer configuration. Common Event Infrastructure (CEI)
logging will be enabled and the necessary database schema is created in the
Business Process Choreographer Derby database BPEDB. This configuration path
can be ideal if performance is not an important consideration.

High-performance configurations
Interactive configuration tools are provided which give you the freedom to exploit
the full potential of the Business Process Choreographer Observer architecture. For
example, in an ideal configuration for performance in a production system, the
three Business Process Choreographer elements run on separate machines, and the
Business Process Choreographer Observer has its own database.

138

Business Process Choreographer

Observer GUI
(browser)

WebSphere Process Server


Business Process
Choreographer
(process and human
task containers)

Business Process
Choreographer
database

CEI Event Server


Event collector application
(includes the transformer)

Observer
application

Observer
database

Figure 3. Business Process Choreographer Observer setup for production performance

If you want to use a separate database for the Business Process Choreographer
Observer, or to add the Business Process Choreographer Observer to an existing
Business Process Choreographer configuration in a clustered setup, or to use more
sophisticated database options, perform Configuring the Business Process
Choreographer Observer on page 207.

In a network deployment environment


The following constraints apply if you want to configure Business Process
Choreographer Observer in a network deployment environment.
v CEI must be configured in your cell.
v As illustrated in the previous figure, the Business Process Choreographer event
collector must be configured on a deployment target where the CEI Event server
is configured. If the CEI Event server is configured on a different cluster than
Business Process Choreographer, you must configure the Business Process
Choreographer event collector on a deployment target where the CEI Event
server is configured. The Business Process Choreographer Observer application
does not need to be installed on the same machine as the event collector.

Chapter 3. Planning to configure Business Process Choreographer

139

140

Business Process Choreographer

Chapter 4. Configuring Business Process Choreographer


Business Process Choreographer must be configured before you install any
enterprise applications that contain business processes or human tasks.
Before you begin
You have completed Chapter 3, Planning to configure Business Process
Choreographer, on page 95.
About this task
Depending on your chosen configuration path, perform one of the following:
v For any of the following non-production configuration paths:
Basic sample
Sample with organization
Non-production deployment environment
Perform Using the Installer or Profile Management Tool to configure Business
Process Choreographer.
v For the Production deployment environment configuration path, perform
Using the administrative consoles deployment environment wizard to
configure Business Process Choreographer on page 144.
v For the Flexible custom configuration configuration path, depending on the
tool you want to use, perform one of the following:
Using the administrative consoles Business Process Choreographer
configuration page on page 147
Using the bpeconfig.jacl script to configure Business Process Choreographer
on page 150
Results
Business Process Choreographer is configured.
What to do next
You can start to customize your setup.

Using the Installer or Profile Management Tool to configure Business


Process Choreographer
There are five easy ways to create a non-production Business Process
Choreographer configuration.
Before you begin
You have completed Planning to create a basic sample Business Process
Choreographer configuration on page 101 and you have decided which flavor of
non-production system you want, as summarized in Table 4 on page 97.
Procedure
Copyright IBM Corp. 2006, 2008

141

1. Depending on the configuration path you selected, perform one of steps 1a - 1c.
a. If you want the Basic sample Business Process Choreographer
configuration which does not include a sample organization for people
assignment and substitution:
1) Start the Installer or Profile Management Tool.
v For the Installer:
Make sure that you select the Typical Installation option.
Make sure that you select the Stand-alone server option.
Make sure that you enable Administrative security.
v For the Profile Management Tool:
Make sure that you create a WebSphere Process Server profile.
Make sure that you select the Stand-alone server profile option.
Make sure that you select the Typical profile creation option.
Make sure that you select Enable administrative security.
b. If you want the Sample with organization Business Process
Choreographer configuration which includes a sample 15 person
organization for people assignment and substitution:
1) Start the Profile Management Tool.
2) Make sure that you create a WebSphere Process Server profile.
3) Make sure that you select the Stand-alone server profile option.
4) Make sure that you select the Advanced option.
5) Make sure that you select the Create server from development template
option.
6) Make sure that you select Enable administrative security.
7) Make sure that you select Configure a sample Business Process
Choreographer.
c. If you want a Non-production deployment environment Business Process
Choreographer configuration based on a deployment environment pattern:
1) Start the Installer or Profile Management Tool.
v For the Installer:
Make sure that you select the Deployment environment
installation option.
Make sure that you create a deployment manager.
You can base the Business Process Choreographer configuration on
any of the following patterns:
- Remote Messaging and Remote Support
- Remote Messaging
- Single Cluster
Make sure that you enable Administrative security, otherwise you
will not get a Business Process Choreographer configuration.
v For the Profile Management Tool:
Make sure that you create a WebSphere Process Server profile.
Make sure that you select the Deployment manager profile option.
You can base the Business Process Choreographer configuration on
any of the following patterns:
- Remote Messaging and Remote Support

142

Business Process Choreographer

- Remote Messaging
- Single Cluster
Make sure that you enable Administrative security, otherwise you
will not get the Business Process Choreographer sample.
2) Create and federate the custom profiles.
2. Optional: Perform Verifying that Business Process Choreographer works on
page 267.
3. Optional: If you want to change the JMS authentication user IDs, the run-as
user IDs, or the mappings of roles onto users and groups, click Security
Business Integration security to change the security settings.
4. If you configured Business Process Choreographer in a clustered environment,
and you will use the Business Process Choreographer Explorer, the Business
Space, or a client that uses the Representational State Transfer (REST) API, you
must change the default context roots for the REST API so that they are unique
for each combination of host name and port. To set the context roots perform
the following:
a. In the administrative console click Applications Enterprise Applications
BPEContainer_node_server Context Root for Web Modules
b. Make sure that the context roots for the Web modules BFMRESTAPI and
HTMRESTAPI are correct and unique.
Note: If you change these context roots, you must make sure that the
environment entries for the REST API URLs used by Web modules such as the
Business Process Choreographer Explorer and the Business Space match the
new context root values.
5. Optional: Change settings for the Human Task Manager:
v If you want to change any of the Human Task Manager settings for the
escalation e-mails, such as the sender address or the URL prefix for the
Business Process Choreographer Explorer, click Servers Application servers
server_name or Servers Clusters cluster_name if Business Process
Choreographer is configured on a cluster, then under Business Integration,
expand Business Process Choreographer Container, click Human Task
Manager, and make your changes.
v If you want to change the e-mail server address, port number, the user ID, or
password for the e-mail server, click Resources Mail Mail sessions ,
select Cell scope, then click HTM mail session, and make your changes.
6. Depending on the type of people directory provider that you use for people
assignment, you might need to configure it:
v The system and user registry people directory providers can be used without
configuring them.
v If you are using Lightweight Directory Access Protocol (LDAP), perform
Configuring the LDAP people directory provider on page 194.
v If you are using the Virtual Member Manager (VMM), perform Configuring
the Virtual Member Manager people directory provider on page 192.
7. Optional: If you configured VMM, and you want to use people substitution,
perform Configuring people substitution on page 199.
8. Optional: If you want to use group work items, use the administrative console
to enable them. Click Servers Application servers server_name or Servers
Clusters cluster_name if Business Process Choreographer is configured on a
cluster, then under Business Integration, expand Business Process
Choreographer Container, click Human Task Manager, and select Enable
group work items.
Chapter 4. Configuring Business Process Choreographer

143

9. Optional: If you want to configure a remote Business Process Choreographer


client that uses the WebSphere Process Server client, perform, Configuring a
remote client application on page 263.
Results
Business Process Choreographer is configured.

Using the administrative consoles deployment environment wizard to


configure Business Process Choreographer
Using the administrative consoles deployment environment wizard, you can create
a pattern-based configuration that includes Business Process Choreographer. If the
Business Process Choreographer configuration has its own database, the
configuration can be suitable for a production system.
Before you begin
You have performed Planning to use the administrative consoles deployment
environment wizard on page 104.
Procedure
1. Start the deployment environment wizard. In the administrative console click
Servers Deployment Environments New. As you enter other
configuration parameters, make sure that you enter the values that you
planned in Planning to use the administrative consoles deployment
environment wizard on page 104:
a. You can base the Business Process Choreographer configuration on any of
the following patterns:
v Remote Messaging and Remote Support
v Remote Messaging
v Single Cluster
v Custom
b. On the security page, you can set the user name and password that will be
used as the authentication alias for Business Process Choreographer, which
is identified as component WBI_BPC.
c. On the database page, if you want to use separate databases for Business
Process Choreographer, the Business Process Choreographer Explorer, or
the Business Process Choreographer messaging engine, change the default
data sources from the default values to the values that you planned.
d. On the Business Process Choreographer page, specify the context roots,
security parameters, and mail session parameters that you planned for this
configuration.
2. If you specified a separate database for Business Process Choreographer,
perform Using a generated SQL script to create the database schema for
Business Process Choreographer on page 176. Otherwise, if you did not
specify a separate database and you are not using a Derby database, make
sure that the empty database exists so that Business Process Choreographer
can create the default schema in the database the first time that it accesses the
database.
3. If you specified a separate database for Business Process Choreographer
Observer, perform Preparing a database for the Business Process
Choreographer Observer on page 208. Otherwise, for a non-Derby database,

144

Business Process Choreographer

make sure that the empty database exists so that Business Process
Choreographer can create the default schema in the database the first time
that it accesses the database.
4. If you specified a separate database for Business Process Choreographer
messaging engine, make sure that the database exists.
v If you want to use the Create tables option to have the messaging engine
create the default schema the first time that it uses the database, grant the
database user ID the rights to create tables and views in the schema that
you planned to use.
v Otherwise, if you will not use the Create tables option, create the tables
before the default messaging provider tries to access the database. You can
use the sibDDLGenerator utility that is in the bin subdirectory of your
install_root directory to generate a DDL file that can be used to create the
tables.
5. For each node where Business Process Choreographer is configured, make
sure that the environment variables for the JDBC drivers are set. On a cluster,
you must perform this for every node that hosts a cluster member.
a. Click Environment WebSphere variables, for Scope, select the node
where Business Process Choreographer is configured.
b. Select the environment variable for your JDBC provider:
v For Derby, you do not need to set any environment variable.
v For DB2 on Linux, UNIX, Windows, or z/OS, using the CLI driver,
select DB2_JDBC_DRIVER_PATH.
v For DB2 on Linux, UNIX, Windows, or z/OS, using the Universal
driver, select DB2UNIVERSAL_JDBC_DRIVER_PATH.
v For DB2 on i5/OS, using the native driver, select
OS400_NATIVE_JDBC_DRIVER_PATH.
v For DB2 on i5/OS, using the toolbox driver, select
OS400_TOOLBOX_JDBC_DRIVER_PATH.
v For Oracle, select ORACLE_JDBC_DRIVER_PATH.
v For Informix, select INFORMIX_JDBC_DRIVER_PATH.
v For SQL Server using the WebSphere embedded ConnectJDBC driver
you do not need to set any environment variable.
v For SQL Server using the DataDirect ConnectJDBC type-4 driver, select
CONNECTJDBC_JDBC_DRIVER_PATH.
c. Set the environment variable to point to the location of the JDBC drivers
JAR file, or files.
6. Activate Business Process Choreographer: Perform Activating Business
Process Choreographer on page 267.
7. Optional: Verify that the basic Business Process Choreographer configuration
works: Perform Verifying that Business Process Choreographer works on
page 267.
8. Optional: Change settings for the Human Task Manager:
v If you want to change any of the Human Task Manager settings for the
escalation e-mails, such as the sender address or the URL prefix for the
Business Process Choreographer Explorer, click Servers Application
servers server_name or Servers Clusters cluster_name if Business
Process Choreographer is configured on a cluster, then under Business
Integration, expand Business Process Choreographer Container, click
Human Task Manager, and make your changes.

Chapter 4. Configuring Business Process Choreographer

145

v If you want to change the e-mail server address, port number, the user ID,
or password for the e-mail server, click Resources Mail Mail sessions ,
select Cell scope, then click HTM mail session, and make your changes.
9. If you configured Business Process Choreographer in a clustered environment,
and you will use the Business Process Choreographer Explorer, the Business
Space, or a client that uses the Representational State Transfer (REST) API, you
must change the default context roots for the REST API so that they are
unique for each combination of host name and port. To set the context roots
perform the following:
a. In the administrative console click Applications Enterprise Applications
BPEContainer_node_server Context Root for Web Modules
b. Make sure that the context roots for the Web modules BFMRESTAPI and
HTMRESTAPI are correct and unique.
Note: If you change these context roots, you must make sure that the
environment entries for the REST API URLs used by Web modules such as the
Business Process Choreographer Explorer and the Business Space match the
new context root values.
10. Depending on the type of people directory provider that you use for people
assignment, you might need to configure it:
v The system and user registry people directory providers can be used
without configuring them.
v If you are using Lightweight Directory Access Protocol (LDAP), perform
Configuring the LDAP people directory provider on page 194.
v If you are using the Virtual Member Manager (VMM), perform
Configuring the Virtual Member Manager people directory provider on
page 192.
11. Optional: If you configured VMM, and you want to use people substitution,
perform Configuring people substitution on page 199.
12. Optional: If you want to use group work items, use the administrative console
to enable them. Click Servers Application servers server_name or Servers
Clusters cluster_name if Business Process Choreographer is configured on
a cluster, then under Business Integration, expand Business Process
Choreographer Container, click Human Task Manager, and select Enable
group work items.
13. Optional: If you want to configure a remote Business Process Choreographer
client that uses the WebSphere Process Server client, perform, Configuring a
remote client application on page 263.
14. If you have WebSphere application security enabled and you have a
long-running process that calls a remote EJB method, make sure that your
Common Secure Interoperability Version 2 (CSIv2) inbound authentication
configuration has CSIv2 identity assertion enabled. For more information
about this, refer to Configuring Common Secure Interoperability Version 2
inbound authentication.
Results
Business Process Choreographer is configured for the deployment environment
that you selected.

146

Business Process Choreographer

Using the administrative consoles Business Process Choreographer


configuration page
Describes how to use the administrative consoles Business Process Choreographer
configuration page to create a configuration on a given server or cluster.
About this task
You must configure the necessary resources and install the Business Process
Choreographer applications before you can run applications that contain business
processes or human tasks.
Procedure
1. If you selected the Business Process Choreographer sample configuration
option when you created a default profile, the Business Flow Manager,
Human Task Manager, Business Process Choreographer Explorer, and Business
Process Choreographer Observer are already configured.
You can check if they are configured, by looking in the administrative console
for enterprise applications with names that start with:
v BPCECollector
v BPCExplorer
v BPCObserver
v BPEContainer
v HTM_PredefinedTasks
v TaskContainer
The sample configuration uses a Derby database, and is not suitable for a
production system. Because you can only have one Business Process
Choreographer configuration on a deployment target, you must remove the
sample configuration, as described in Chapter 5, Removing the Business
Process Choreographer configuration, on page 271 before you can continue
configuring Business Process Choreographer.
2. If you have a network deployment environment, make sure that the Service
Component Architecture (SCA) is configured:
a. If you want to configure Business Process Choreographer on a server, click
Servers Application servers serverName, then in the Business
Integration section, click Service Component Architecture.
b. If you want to configure Business Process Choreographer on a cluster, click
Servers Clusters clusterName, then in the Business Integration
section, click Service Component Architecture.
c. If it is not enabled, select Support the Service Component Architecture
components.
3. Create the database for the data store for the Business Process Choreographer
messaging engine:
v If you want to use the Create tables option on the Business Process
Choreographer configuration page, to have the messaging engine create the
default schema the first time that it uses the database, perform the
following:
a. If the database does not already exist, create it.
b. Grant the database user ID the rights to create tables and views in the
schema that you planned to use.

Chapter 4. Configuring Business Process Choreographer

147

v Otherwise, if you will not use the Create tables option, create the tables
before the default messaging provider tries to access the database. You can
use the sibDDLGenerator utility that is in the bin subdirectory of your
install_root directory to generate a DDL file that can be used to create the
tables.
4. For each node where Business Process Choreographer is configured, make
sure that the environment variables for the JDBC drivers are set. On a cluster,
you must perform this for every node that hosts a cluster member.
a. Click Environment WebSphere variables, for Scope, select the node
where Business Process Choreographer is configured.
b. Select the environment variable for your JDBC provider:
v For Derby, you do not need to set any environment variable.
v For DB2 on Linux, UNIX, Windows, or z/OS, using the CLI driver,
select DB2_JDBC_DRIVER_PATH.

5.

6.

7.

8.
9.
10.

148

v For DB2 on Linux, UNIX, Windows, or z/OS, using the Universal


driver, select DB2UNIVERSAL_JDBC_DRIVER_PATH.
v For DB2 on i5/OS, using the native driver, select
OS400_NATIVE_JDBC_DRIVER_PATH.
v For DB2 on i5/OS, using the toolbox driver, select
OS400_TOOLBOX_JDBC_DRIVER_PATH.
v For Oracle, select ORACLE_JDBC_DRIVER_PATH.
v For Informix, select INFORMIX_JDBC_DRIVER_PATH.
v For SQL Server using the WebSphere embedded ConnectJDBC driver
you do not need to set any environment variable.
v For SQL Server using the DataDirect ConnectJDBC type-4 driver, select
CONNECTJDBC_JDBC_DRIVER_PATH.
c. Set the environment variable to point to the location of the JDBC drivers
JAR file, or files.
In the administrative console, select the server or cluster where you want to
configure Business Process Choreographer. Click one of the following:
v Servers Application Servers serverName
v Servers Clusters clusterName
Where serverName or clusterName is the name of the server or cluster.
Go to the Business Process Choreographer configuration page: In the
Container Settings section, expand Business Process Choreographer
Container Settings and click Business Process Choreographer Containers.
Verify that Business Process Choreographer is not configured. There should be
a message indicating that the Business Process Choreographer containers
(Business Flow Manager and Human Task Manager) are not currently
installed.
If the Business Flow Manager and Human Task Manager are already installed,
perform Chapter 5, Removing the Business Process Choreographer
configuration, on page 271 before continuing with the next step.
Enter the values and select the options that you planned for the Business
Process Choreographer configuration on this server or cluster.
Click Apply. Information is displayed reporting the progress deploying and
configuring Business Process Choreographer.
If the installation succeeded, click Save Master Configuration, then click
Save. Otherwise, discard the changes, check the administrative console and

Business Process Choreographer

the SystemOut.log file on the Deployment Manager or server for any error
messages that can help you correct the problem, then try again.
11. To create the database schema, you or your database administrator should
perform the actions described in Using a generated SQL script to create the
database schema for Business Process Choreographer on page 176 before you
activate Business Process Choreographer in step 12.
Note: If your database is local, and it will exist by the time you activate
Business Process Choreographer in step 9 on page 156, and you do not
perform the actions described in Using a generated SQL script to create the
database schema for Business Process Choreographer on page 176, the default
schema will be created the first time that Business Process Choreographer
accesses the database.
12. Activate Business Process Choreographer: Perform Activating Business
Process Choreographer on page 267.
13. Optional: Verify that the basic Business Process Choreographer configuration
works: Perform Verifying that Business Process Choreographer works on
page 267.
14. Optional: Change settings for the Human Task Manager:
v If you want to change any of the Human Task Manager settings for the
escalation e-mails, such as the sender address or the URL prefix for the
Business Process Choreographer Explorer, click Servers Application
servers server_name or Servers Clusters cluster_name if Business
Process Choreographer is configured on a cluster, then under Business
Integration, expand Business Process Choreographer Container, click
Human Task Manager, and make your changes.
v If you want to change the e-mail server address, port number, the user ID,
or password for the e-mail server, click Resources Mail Mail sessions ,
select Cell scope, then click HTM mail session, and make your changes.
15. Depending on the type of people directory provider that you use for people
assignment, you might need to configure it:
v The system and user registry people directory providers can be used
without configuring them.
v If you are using Lightweight Directory Access Protocol (LDAP), perform
Configuring the LDAP people directory provider on page 194.
v If you are using the Virtual Member Manager (VMM), perform
Configuring the Virtual Member Manager people directory provider on
page 192.
16. Optional: If you configured VMM, and you want to use people substitution,
perform Configuring people substitution on page 199.
17. Optional: If you want to use group work items, use the administrative console
to enable them. Click Servers Application servers server_name or Servers
Clusters cluster_name if Business Process Choreographer is configured on
a cluster, then under Business Integration, expand Business Process
Choreographer Container, click Human Task Manager, and select Enable
group work items.
18. If you have WebSphere application security enabled and you have a
long-running process that calls a remote EJB method, make sure that your
Common Secure Interoperability Version 2 (CSIv2) inbound authentication
configuration has CSIv2 identity assertion enabled. For more information
about this, refer to Configuring Common Secure Interoperability Version 2
inbound authentication.
Chapter 4. Configuring Business Process Choreographer

149

19. If you configured Business Process Choreographer in a clustered environment,


and you will use the Business Process Choreographer Explorer, the Business
Space, or a client that uses the Representational State Transfer (REST) API, you
must change the default context roots for the REST API so that they are
unique for each combination of host name and port. To set the context roots
perform the following:
a. In the administrative console click Applications Enterprise Applications
BPEContainer_node_server Context Root for Web Modules
b. Make sure that the context roots for the Web modules BFMRESTAPI and
HTMRESTAPI are correct and unique.
Note: If you change these context roots, you must make sure that the
environment entries for the REST API URLs used by Web modules such as the
Business Process Choreographer Explorer and the Business Space match the
new context root values.
20. Optional: If you have not yet installed and configured Business Process
Choreographer Explorer, you can configure it now. Perform Configuring
Business Process Choreographer Explorer on page 202.
21. Optional: If you have not yet installed and configured Business Process
Choreographer Observer, you can configure it now. Perform, Configuring the
Business Process Choreographer Observer on page 207.
22. Optional: If you want to configure a remote Business Process Choreographer
client that uses the WebSphere Process Server client, perform, Configuring a
remote client application on page 263.
Results
Business Process Choreographer is configured.

Using the bpeconfig.jacl script to configure Business Process


Choreographer
Describes how to use the bpeconfig.jacl script to configure Business Process
Choreographer and all the necessary resources on a given server or cluster.
Procedure
1. Make sure that you know which options and parameters you are going to use.
Refer to the values you planned in Chapter 3, Planning to configure Business
Process Choreographer, on page 95. You must include all the required
parameters and options in the batch file or on the command line. Otherwise,
any required parameters that are not provided will be prompted for. For
detailed information about the script, examples, its options and parameters,
see bpeconfig.jacl script file on page 157.
Option

Description

If the server (or in a network deployment


environment, the deployment manager) is
not running

Use the option:


-conntype NONE
Do not use this option if the server (or
deployment manager) is running.

If administrative security is enabled

Include the parameters:


-user userName
-password userPassword

150

Business Process Choreographer

Option

Description

If you are not using the default profile

Include the parameter:


-profileName profileName

If you are not configuring Business Process Include either the parameter:
Choreographer on the default server
-cluster clusterName
or both parameters:
-node nodeName
-server serverName
Because the script always creates a
Business Process Choreographer
configuration

Include the parameters required for the


Business Flow Manager and Human Task
Manager:
{-adminBFMUsers userList |
-adminBFMGroups groupList}
{-monitorBFMUsers userList |
-monitorBFMGroups groupList}
-jmsBFMRunAsUser userID
-jmsBFMRunAsPwd password
{-adminHTMUsers userList |
-adminHTMGroups groupList}
{-monitorHTMUsers userList |
-monitorHTMGroups groupList}
-jmsHTMRunAsUser userID
-jmsHTMRunAsPwd password
-contextRootBFMWS contextRootBFMWS
-contextRootBFMREST contextRootBFMREST
-contextRootHTMWS contextRootHTMWS
-contextRootHTMREST contextRootHTMREST
For the parameter pairs ending in Users and
Groups you must specify either one or both
parameters. The two parameters starting
with contextRoot are optional.

If you want to enable a simple mail


Include the parameter:
transfer protocol (SMTP) server for sending -mailServerName mailServerName
escalation e-mails
If the mail server requires authentication,
also include the parameters:
-mailUser mailUserID
-mailPwd mailPassword

Chapter 4. Configuring Business Process Choreographer

151

Option

Description

Because you can either have the script file Use the option
create the database, or just have it generate -createDB { yes | no }
the SQL script without running the scripts
If you select yes, the bpeconfig.jacl script
will generate and run an SQL file to create
the database objects in the default table
space, which is not suitable for a
high-performance system. In this case also
plan to stop the server and use the
-conntype NONE option.
If you select no, and the database does not
already exist, then you or your database
administrator must run the generated SQL
script. For a high-performance system,
specify no, because you will need to
customize the SQL script before running it.
Also specify no if you do not have the
authority to create the database yourself, so
that you can provide the SQL script to your
database administrator to customize and
run.
You must also specify no if you are using a
database which has restricted support.
Restriction: The script cannot create the
following types of databases:
v DB2 for z/OS
v Oracle
v A remote Microsoft SQL Server
v A remote Informix Dynamic Server
If you select yes and you are running the
script in connected mode, creating the
database or schema can fail if it takes longer
than the a default timeout of 3 minutes.

152

Business Process Choreographer

Option

Description

Because every Business Process


Choreographer configuration requires
access to a database

Include the parameter:


-dbType databaseType
Also provide the parameters required for
your database type (see bpeconfig.jacl
script file on page 157 for details):
-dbVersion version
-dbHome databaseInstallPath
-dbJava JDBCDriverPath
-dbName databaseName
-dbUser databaseUser
-dbPwd databasePassword
-dbAdmin databaseAdministratorUserID
-driverType JDBCDriverType
-dbTablespaceDir databaseTablespacePath
-dbServerName databaseServerName
-dbServerPort databaseServerPort
-dbStorageGroup DB2zOSStorageGroup
-dbConnectionTarget DB2zOSSubSystem
-dbSchema schemaQualifier
-dbInstance InformixInstance
When running the script in batch mode on a
cluster, if your database requires the -dbJava
parameter, specify the parameter for each
node that hosts a cluster member in the
following way:
-dbJava.nodeName JDBCDriverPath
_on_nodeName
Note: If you are using one of the following
databases, bpeconfig.jacl can also create the
database instance:
v A local DB2 for Linux, UNIX, or Windows
v DB2 on iSeries
v Derby Embedded
v Derby Network database and the server is
running

Because every Business Process


Choreographer configuration uses a JMS
provider

Include the parameter:


-mqType { WPM | MQSeries }
Also provide the parameters required for
your JMS provider (see bpeconfig.jacl script
file on page 157 for details).
-createQM { yes | no }
-qmNameGet getQueueManagerName
-mqClusterName mqClusterName
-qmNamePut putQueueManagerName
-mqHome MQInstallationDirectory
-mqUser JMSProviderUserID
-mqPwd JMSProviderPassword
Note: The MQSeries option is deprecated.

Chapter 4. Configuring Business Process Choreographer

153

Option

Description

If you are using the -mqType WPM option,


specify the message engine store settings

Include the following parameters:


-meStoreType { FILESTORE | DATASTORE }
-mqCreateTables { true | false }
-mqSchemaName mqSchemaName
-medbUser meDatabaseUser
-medbPwd meDatabasePassword
and optionally include:
-mqDataSource datasourceName

Because the script always configures a


Business Process Choreographer Explorer

Include any of these optional parameters:


-contextRootExplorer explorerContextRoot
-explorerHost explorerURL
-hostName explorerVirtualHostname
-maxListEntries maximum
-remoteCluster clusterName
-remoteNode nodeName
-remoteServer serverName
-restAPIBFM restAPIURL
-restAPIHTM restAPIURL
For more information about these
parameters, including default values, see
Using the clientconfig.jacl script file to
configure the Business Process
Choreographer Explorer on page 204.

Know whether you want to install and


configure the Business Process
Choreographer Observer, or event collector
applications on the deployment target

Use the options:


-createEventCollector { yes | no }
-createObserver { yes | no }
These options can only be used when
running bpeconfig.jacl in batch mode, and
are not suitable for a high performance
system. For a production system, perform
Configuring the Business Process
Choreographer Observer on page 207.

2. If you selected the Business Process Choreographer sample configuration


option when you created a default profile, the Business Flow Manager,
Human Task Manager, Business Process Choreographer Explorer, and Business
Process Choreographer Observer are already configured.
You can check if they are configured, by looking in the administrative console
for enterprise applications with names that start with:
v BPCECollector
v BPCExplorer
v BPCObserver
v BPEContainer
v HTM_PredefinedTasks
v TaskContainer
The sample configuration uses a Derby database, and is not suitable for a
production system. Because you can only have one Business Process
Choreographer configuration on a deployment target, you must remove the
sample configuration, as described in Chapter 5, Removing the Business
Process Choreographer configuration, on page 271 before you can continue
configuring Business Process Choreographer.

154

Business Process Choreographer

3. If you have a network deployment environment, make sure that the Service
Component Architecture (SCA) is configured:
a. If you want to configure Business Process Choreographer on a server, click
Servers Application servers serverName, then in the Business
Integration section, click Service Component Architecture.
b. If you want to configure Business Process Choreographer on a cluster, click
Servers Clusters clusterName, then in the Business Integration
section, click Service Component Architecture.
c. If it is not enabled, select Support the Service Component Architecture
components.
4. If you are using WebSphere Platform Messaging (WPM) as the JMS provider,
and did not use either of the options -meStoreType DATASTORE with a Derby
Embedded database, or -meStoreType FILESTORE then create the database for
the data store for the Business Process Choreographer messaging engine:
v If you want to use the -mqCreateTables yes option to have the messaging
engine create the default schema the first time that it uses the database,
perform the following:
a. If the database does not already exist, create it.
b. Grant the database user ID the rights to create tables and views in the
schema that you planned to use.
v Otherwise, if you will use the -mqCreateTables no option, create the tables
before the default messaging provider tries to access the database. You can
use the sibDDLGenerator utility that is in the bin subdirectory of your
install_root directory to generate a DDL file that can be used to create the
tables.
5. If you plan to use the option -createDB yes to run the generated SQL scripts
to create the database schema:
a. If you are using one of the following databases:
v
v
v
v

DB2 for z/OS


Oracle
a remote Microsoft SQL Server
a remote Informix Dynamic Server

and your database does not already exist, create an empty database
manually according to the documentation for your database.
b. Make sure that the database client, for example db2.exe, is on the path for
the scripting client.
c. Make sure that the application server is stopped.
6. Invoke the bpeconfig.jacl script file, either in batch mode providing the
options and configuration parameters that you planned, or in interactive
mode, For details about the script file, refer to bpeconfig.jacl script file on
page 157.
7. If you are using the WebSphere MQ Java Message Service (JMS) provider, and
you used the -createQM no option to prevent the script from creating the
queue manager and queues, create the queue manager and queues now by
performing Creating the queue manager and queues for Business Process
Choreographer on page 172.
8. If you either used the -createDB no option to defer that creation of the
database, or if the bpeconfig.jacl script failed create the database, you or your
database administrator should perform the actions described in Using a

Chapter 4. Configuring Business Process Choreographer

155

generated SQL script to create the database schema for Business Process
Choreographer on page 176 before you activate Business Process
Choreographer in step 9.

9.
10.

11.

12.

Note: If your database is local, and it will exist by the time you activate
Business Process Choreographer in step 9, and you do not perform the actions
described in Using a generated SQL script to create the database schema for
Business Process Choreographer on page 176, the default schema will be
created the first time that Business Process Choreographer accesses the
database.
Activate Business Process Choreographer: Perform Activating Business
Process Choreographer on page 267.
Optional: Verify that the basic Business Process Choreographer configuration
works: Perform Verifying that Business Process Choreographer works on
page 267.
Optional: If you want to change the JMS authentication user IDs, the run-as
user IDs, or the mappings of roles onto users and groups, click Security
Business Integration security to change the security settings.
Optional: Change settings for the Human Task Manager:
v If you want to change any of the Human Task Manager settings for the
escalation e-mails, such as the sender address or the URL prefix for the
Business Process Choreographer Explorer, click Servers Application
servers server_name or Servers Clusters cluster_name if Business
Process Choreographer is configured on a cluster, then under Business
Integration, expand Business Process Choreographer Container, click
Human Task Manager, and make your changes.
v If you want to change the e-mail server address, port number, the user ID,
or password for the e-mail server, click Resources Mail Mail sessions ,
select Cell scope, then click HTM mail session, and make your changes.

13. Depending on the type of people directory provider that you use for people
assignment, you might need to configure it:
v The system and user registry people directory providers can be used
without configuring them.
v If you are using Lightweight Directory Access Protocol (LDAP), perform
Configuring the LDAP people directory provider on page 194.
v If you are using the Virtual Member Manager (VMM), perform
Configuring the Virtual Member Manager people directory provider on
page 192.
14. Optional: If you configured VMM, and you want to use people substitution,
perform Configuring people substitution on page 199.
15. Optional: If you want to use group work items, use the administrative console
to enable them. Click Servers Application servers server_name or Servers
Clusters cluster_name if Business Process Choreographer is configured on
a cluster, then under Business Integration, expand Business Process
Choreographer Container, click Human Task Manager, and select Enable
group work items.
16. If you have WebSphere application security enabled and you have a
long-running process that calls a remote EJB method, make sure that your
Common Secure Interoperability Version 2 (CSIv2) inbound authentication
configuration has CSIv2 identity assertion enabled. For more information
about this, refer to Configuring Common Secure Interoperability Version 2
inbound authentication.

156

Business Process Choreographer

17. If you configured Business Process Choreographer in a clustered environment,


and you will use the Business Process Choreographer Explorer, the Business
Space, or a client that uses the Representational State Transfer (REST) API, you
must change the default context roots for the REST API so that they are
unique for each combination of host name and port. To set the context roots
perform the following:
a. In the administrative console click Applications Enterprise Applications
BPEContainer_node_server Context Root for Web Modules
b. Make sure that the context roots for the Web modules BFMRESTAPI and
HTMRESTAPI are correct and unique.
Note: If you change these context roots, you must make sure that the
environment entries for the REST API URLs used by Web modules such as the
Business Process Choreographer Explorer and the Business Space match the
new context root values.
18. Optional: If you have not yet installed and configured Business Process
Choreographer Explorer, you can configure it now. Perform Configuring
Business Process Choreographer Explorer on page 202.
19. Optional: If you have not yet installed and configured Business Process
Choreographer Observer, you can configure it now. Perform, Configuring the
Business Process Choreographer Observer on page 207.
20. Optional: If you want to configure a remote Business Process Choreographer
client that uses the WebSphere Process Server client, perform, Configuring a
remote client application on page 263.
Results
Business Process Choreographer is configured.

bpeconfig.jacl script file


This script file configures Business Process Choreographer and all the necessary
resources on a server or cluster.

Purpose
This script can either be run interactively, or in batch mode. It can create a local
database, the necessary messaging resources, and can optionally configure the
Business Process Choreographer Explorer and Business Process Choreographer
Observer.

Location
The bpeconfig.jacl script file is located in the Business Process Choreographer
config directory:
v On Linux, UNIX, and i5/OS platforms: In the directory install_root/
ProcessChoreographer/config
v On Windows platforms: In the directory install_root\ProcessChoreographer\
config

Restrictions
This script has the following restrictions:

Chapter 4. Configuring Business Process Choreographer

157

For a DB2 for z/OS database


The bpeconfig.jacl script cannot create a DB2 for z/OS database. You must
create it manually.
For a DB2 database
The bpeconfig.jacl script cannot create a database if the Universal Driver
type 4 is selected even if DB2 is installed locally.
For an Oracle database
The bpeconfig.jacl script cannot create an Oracle database. If you want to
use an Oracle database for Business Process Choreographer, you must
create the database manually.
For a Microsoft SQL Server database
The bpeconfig.jacl script cannot create a remote database. To create a local
database, use a type-2 JDBC driver, and do not specify the -dbServerName
parameter. If you want to use a remote Microsoft SQL Server database for
Business Process Choreographer, you must create the database manually.

Running the script in a stand-alone server environment


Any parameters for the wsadmin command must be provided on the command
line, if they are not specified, they will not be prompted for. In a stand-alone server
environment:
v Include the -conntype NONE option only if the application server is not running.
v If the server is running and WebSphere administrative security is enabled,
include the -user and -password options.
v If you are not configuring the default profile, add the -profileName option.

Running the script in a network deployment environment


Any parameters for the wsadmin command must be provided on the command
line, if they are not specified, they will not be prompted for. In a network
deployment environment:
v Run the script on the deployment manager node.
v Include the -conntype NONE option only if the deployment manager is not
running.
v If WebSphere administrative security is enabled, include the -user and
-password options.
v If you are not configuring the default profile, add the -profileName option.

Configuring the business process container, Business Process


Choreographer Explorer, and Business Process Choreographer
Observer non-interactively
If you provide the necessary parameters on the command line, you will not be
prompted for them. To configure Business Process Choreographer, enter one of the
following commands:
On Linux and UNIX platforms, if your current directory is install_root, enter the
command:
bin/wsadmin.sh -f ProcessChoreographer/config/bpeconfig.jacl parameters

On i5/OS platforms, if your current directory is install_root, enter the command:


bin/wsadmin -f ProcessChoreographer/config/bpeconfig.jacl parameters

158

Business Process Choreographer

On Windows platforms, if your current directory is install_root, enter the command:


bin\wsadmin -f ProcessChoreographer/config/bpeconfig.jacl parameters

where parameters are as follows:


-adminBFMUsers userList
-adminBFMGroups groupList
-adminHTMUsers userList
-adminHTMGroups groupList
-cluster clusterName
-conntype NONE
-contextRootBFMWS contextRootBFMWS
-contextRootBFMREST contextRootBFMREST
-contextRootExplorer explorerContextRoot
-contextRootHTMWS contextRootHTMWS
-contextRootHTMREST contextRootHTMREST
-createDB { yes | no }
-createEventCollector { yes | no }
-createObserver { yes | no }
-createQM { yes | no }
-dbConnectionTarget DB2zOSSubSystem
-dbHome databaseInstallPath
-dbInstance InformixInstance
-dbJava JDBCDriverPath
-dbName databaseName
-dbPwd databasePassword
-dbSchema schemaQualifier
-dbServerName databaseServerName
-dbServerPort databaseServerPort
-dbStorageGroup DB2zOSStorageGroup
-dbTablespaceDir databaseTablespacePath
-dbType databaseType
-dbUser databaseUser
-dbVersion version
-driverType JDBCDriverType
-explorerHost explorerURL
-hostName VirtualHostname
-jmsBFMRunAsPwd password
-jmsBFMRunAsUser userID
-jmsHTMRunAsPwd password
-jmsHTMRunAsUser userID
-mailPwd mailPassword
-mailServerName mailServerName
-mailUser mailUserID
-maxListEntries max
-medbPwd meDatabasePassword
-medbUser meDatabaseUser
-meStoreType { FILESTORE | DATASTORE }
-monitorBFMGroups groupList
-monitorBFMUsers userList
-monitorHTMGroups groupList
-monitorHTMUsers userList
-mqClusterName mqClusterName
-mqCreateTables { true | false }
-mqDataSource datasourceName
-mqHome MQInstallationDirectory
-mqPwd JMSProviderPassword
-mqSchemaName mqSchemaName
-mqType JMSProviderType
-mqUser JMSProviderUserID
-node nodeName
-password userPassword
-precompileJSPs { yes | no }
-profileName profileName
-qmNameGet getQueueManagerName
-qmNamePut putQueueManagerName
-remoteCluster clusterName
Chapter 4. Configuring Business Process Choreographer

159

-remoteNode nodeName
-remoteServer serverName
-restAPIBFM restAPIURL
-restAPIHTM restAPIURL
-server serverName}
-user userName

Note: Some of the above parameters are optional, depending on the values
provided for other parameters. The dependencies between parameters and the
conditions that determine whether a parameter is optional or required are
described for each parameter in the following descriptions. Any required
parameters that are not specified on the command line are prompted for
interactively. If the same parameter is specified more than once, the last value
specified is used.

Parameters
You can use the following parameters when invoking the script using wsadmin:
-adminBFMUsers userList
Where userList is the list of names of users, from the user registry, to which to
map the BPESystemAdministrator Java 2 Enterprise Edition (J2EE) role. The
separator character is the vertical line (|). This property is needed to install the
business process container. This parameter has no default value. Either one or
both of the adminBFMUsers or adminBFMGroups options must be set.
-adminBFMGroups groupList
Where groupList is the list of names of groups, from the user registry, to which
to map the BPESystemAdministrator J2EE role. The separator character is the
vertical line (|). This property is needed to install the business process
container. This parameter has no default value. Either one or both of the
adminBFMUsers or adminBFMGroups options must be set.
-adminHTMUsers userList
Where userList is the list of names of users, from the user registry, to which to
map the TaskSystemAdministrator Java 2 Enterprise Edition (J2EE) role. The
separator character is the vertical line (|). This property is needed to install the
human task container. This parameter has no default value. Either one or both
of the adminHTMUsers or adminHTMGroups options must be set.
-adminHTMGroups groupList
Where groupList is the list of names of groups, from the user registry, to which
to map the TaskSystemAdministrator J2EE role. The separator character is the
vertical line (|). This property is needed to install the human task container.
This parameter has no default value. Either one or both of the
adminHTMUsers or adminHTMGroups options must be set.
-conntype NONE
This specifies that no administration connection is available. Only include this
option if the application server (for stand-alone) or deployment manager (for
network deployment) is not running. This is a wsadmin parameter, if you do
not specify it, you will not be prompted for it.
-contextRootBFMREST contextRootBFMREST
Where contextRootBFMREST is the context root for the REST API endpoint
URL. For the Business Flow Manager (BFM) the default context root on a
server or a cluster is /rest/bpm/bfm.
-contextRootBFMWS contextRootBFMWS
Where contextRootBFMWS is the context root for the Web Service Endpoint

160

Business Process Choreographer

URL. For a Business Flow Manager (BFM), on a server, the default context root
is /BFMIF_${nodeName}_${serverName}. On a cluster, the default is
/BFMIF_clusterName.
-contextRootExplorer contextRootExplorer
Where contextRootExplorer is the context root for the Business Process
Choreographer Explorer. The default value is /bpc, which results in the default
URL of http://host:port/bpc. The context root must be unique for each
combination of host name and port.
-contextRootHTMREST contextRootHTMREST
Where contextRootHTMREST is the context root for the REST API endpoint
URL. For the Human Task Manager (HTM) the default context root on a server
or a cluster is /rest/bpm/htm.
-contextRootHTMWS contextRootHTMWS
Where contextRootHTMWS is the context root for the Web Service Endpoint
URL. For a Human Task Manager (HTM), on a server, the default context root
is /HTMIF_${nodeName}_${serverName}. On a cluster, the default is
/HTMIF_clusterName.
-createDB { yes | no }
Possible values are yes or no. If set to yes, the script will create the database.
For z/OS databases and Oracle, this script cannot create the database, it can
only create the table spaces and tables. For other database types, the default
value is yes. For production systems, use no. If you use yes, the command
prompt from which bpeconfig.jacl is invoked must have the appropriate paths
set to run the corresponding database commands, for example, db2.exe.
-createEventCollector { yes | no}
When run in batch mode, the default is yes, which causes the Business Process
Choreographer event collector application to be configured, which is required
by Business Process Choreographer Observer. Using this option, you cannot
specify a different database, the BPEB database is used by default, which
means that this option is not suitable for a high performance system. If you do
not want it installed, set the value of this parameter to no.
-createObserver { yes | no}
When run in batch mode, the default is yes, which causes the Business Process
Choreographer Observer application to be configured. You can only use this
option in non-interactive mode. Using this option, you cannot specify a
different database, the BPEB database is used by default, which means that this
option is not suitable for a high performance system. If you do not want it
installed, set the value of this parameter to no.
-createQM { yes | no}
Controls whether the script creates a local WebSphere MQ queue manager.
This option only has an effect if the parameter mqType has the value MQSeries,
which is deprecated. The default value for this parameter is yes. Use the value
no if you do not want the script to create the WebSphere MQ queue manager,
for example, if you want to create the queue manager on a different server to
the one where you are running the script.
-dbConnectionTarget DB2zOSSubSystem
Where DB2zOSSubSystem is the DB2 connection target location used to create
the Business Process Choreographer database tables and the data source. This
parameter is only required for DB2 on z/OS. The default value is BPEDB.
-dbHome databaseInstallPath
Where databaseInstallPath is the installation directory of the database system.
Chapter 4. Configuring Business Process Choreographer

161

This parameter is only required for Informix and optionally for DB2 if the
createDB parameter is set to Yes. It is used to create the database or the
database tables, and for creating the data source. The default value, and
requirements depend on the database and on the platform:
For DB2:
v On Windows platforms, the default is current_drive\Program
Files\IBM\SQLLIB where current_drive is the current drive letter.
v On Solaris platforms, the default is /export/home/${dbUser}/sqllib.
v On other platforms, the default is /home/${dbUser}/sqllib.
The directories ${dbHome}/bnd and ${dbHome}/bin must exist.
For Informix:
v On Windows platforms, the default is current_drive\Program
Files\Informix where current_drive is the current drive letter.
v On Solaris and HP-UX platforms, the default is /opt/informix.
v On Linux and AIX platforms, the default is /usr/informix.
The file ${dbHome}/jdbc/lib/ifxjdbc.jar must exist.
-dbInstance InformixInstance
Where InformixInstance is the instance name for a Business Process
Choreographer Informix database. The default value is ids1.
-dbJava JDBCDriverPath
Where JDBCDriverPath is the directory where the JDBC driver is located. This
parameter is only required for the following combinations of database and
driver types:
v DB2 Universal with a type-4 driver. The default value is
databaseInstallPath/java.
v DB2 for i5/OS with a type-2 (Native) driver. The default value is
/QIBM/ProdData/Java400/ext .
v DB2 for i5/OS with the type-4 (Toolbox) driver. The default value is
/QIBM/ProdData/HTTP/Public/jt400/lib/java.
v DB2 for z/OS, with a type-4 driver. The default value is
databaseInstallPath/java.
v Informix. The default value is databaseInstallPath/jdbc/lib.
v MSSQL DataSource with the DataDirect driver type. There is no default
value.
v Oracle. There is no default value.
Where databaseInstallPath is the installation directory for the database system.
When running the script in batch mode on a cluster, if your database requires
the -dbJava parameter, specify the parameter for each node that hosts a cluster
member in the following way:
-dbJava.nodeName JDBCDriverPath_on_nodeName

Where JDBCDriverPath is the path to the JDBC driver and nodeName is the
name of the node.
-dbName databaseName
Where databaseName is the name of the Business Process Choreographer
database. It is used to create the database or the database tables, and for
creating the data source. The default value is BPEDB.

162

Business Process Choreographer

v For Oracle, this is the TNS.


v For Derby Network (not Derby Embedded) this must be an absolute path
name.
v For i5/OS, it is the database name or IASP hardware device name. When
using the Toolbox JDBC driver, the default is *SYSBAS, when using the
Native driver the default is *LOCAL.
-dbPwd databasePassword
Where databasePassword is the password for the user ID databaseUser.
-dbSchema schemaQualifier
For i5/OS, schemaQualifier is the collection name, the default value is BPEDB. For
all other platforms schemaQualifier is the schema qualifier used to create the
Business Process Choreographer database tables and the data source. The
default value is empty, which means to use the implicit schema qualifier,
which depends on the database type being used.
-dbServerName databaseServerName
Where databaseServerName is the name server that hosts the database for
Business Process Choreographer. It is used to create the data source.
v For DB2, the default value is empty. For DB2 UDB, this parameter is
optional, and if it is not specified, a type 2 JDBC driver will be configured
for DB2, otherwise a type 4 JDBC provider will be configured.
v For DB2 on i5/OS, specify the server short name. When using the Toolbox
driver, the default is the short name of the local host.
v For all other database types, the default value is the fully qualified host
name of the local host.
-dbServerPort databaseServerPort
Where databaseServerPort is the TCP/IP port for the database server for
Business Process Choreographer. This parameter is required if dbServerName
is specified.
v For DB2, the default value is 50000.
v For Derby Network, the default value is 1527.
v For Informix, the default value is 1526.
v For MSSQL, the default value is 1433.
v For Oracle with the driver type thin, the default value is 1521.
-dbStorageGroup DB2zOSStorageGroup
Where DB2zOSStorageGroup is the storage group used to create the Business
Process Choreographer database tables. This parameter is only required for
DB2 on z/OS. There is no default value, and must not be empty.
-dbTablespaceDir databaseTablespacePath
Where databaseTablespacePath is the directory where the database table spaces
are created. It is used to create the database and database tables. This
parameter is only required for the following database types:
v For Oracle, there is no default value. You must provide a value.
v For DB2, the default value is empty, which means that no table spaces are
created.
-dbType databaseType
Where databaseType is the database type. This is needed for installing the
business process container, for creating the database or database tables, and for
creating the data source. There is no default value. Possible values are:
v Derby
Chapter 4. Configuring Business Process Choreographer

163

v
v
v
v
v
v

DB2
zOS-DB2
Informix
iSeries-DB2
MSSQL
Oracle

-dbUser databaseUser
Where databaseUser is the user ID to access the database. It is used to create the
data source. The default value depends on the database and platform:
v For DB2 on Windows platforms: db2admin
v For DB2 on other platforms: db2inst1
v
v
v
v

For
For
For
For

Derby Network: The user ID of the currently logged on user


Informix: informix
Oracle: system
MSSQL: The user ID of the currently logged on user

-dbVersion version
Where version is the database version number. It has no default value. It is only
required for the following database types:
v For DB2 for z/OS, version must have either the value 8 or 9.
v For Oracle, version must have either the value 9, 10, or 11.
Note: If you are connecting to an Oracle 11g database, you must set
dbVersion according to data source helper class that you use:
If you use Oracles ojdbc5.jar JDBC driver and WebSpheres Oracle 11
data source helper class, specify dbVersion=11.
If you use Oracles ojdbc14.jar JDBC driver and WebSpheres Oracle 10
data source helper class, you must actually specify dbVersion=10.
v For MSSQL, version must have either the value 2000 if the database has no
Unicode support, or 2000U if the database has Unicode support.
-driverType JDBCDriverType
Where JDBCDriverType is the type of JDBC driver. It is used to create the data
source.
v For DB2, possible values are Universal or CLI.
v For DB2 on i5/OS: possible values are native or toolbox .
v For Derby: possible values are Embedded or Network.
v For Oracle, possible values are oci8 or thin.
v For MSSQL, possible values are Embedded or DataDirect.
-explorerHost explorerURL
Where explorerURL is the URL of the Business Process Choreographer Explorer.
If this parameter is not specified for a non-cluster environments, a default
value is computed, for example, http://localhost:9080. The value of this
parameter is used by the Human Task Manager to link to this explorer
instance.
-hostName VirtualHostname
Where VirtualHostname is the virtual host where the Business Process
Choreographer Explorer, the Web service bindings of the Business Flow

164

Business Process Choreographer

Manager and Human Task Manager APIs, and the REST bindings of the
Business Flow Manager and Human Task Manager APIs will run. The default
value is default_host.
-jmsBFMRunAsPwd password
Where password is the password for the jmsBFMRunAsUser user ID. This
property is required to configure the business process container. This
parameter has no default value. It must be set.
-jmsBFMRunAsUser userID
Where userID is the run-as user ID from the user registry for the J2EE role
JMSAPIUser. This property is required to configure the business process
container. This parameter has no default value. It must be set.
-jmsHTMRunAsPwd password
Where password is the password for the jmsHTMRunAsUser user ID. This
property is required to configure the human task container. This parameter has
no default value. It must be set.
-jmsHTMRunAsUser userID
Where userID is the run-as user ID from the user registry for the J2EE role
EscalationUser. This property is required to configure the human task
container. This parameter has no default value. It must be set.
-mailPwd mailPassword
Where mailPassword is the password for the user ID mailUserID. This parameter
is only needed if the mail server requires authentication. Otherwise, it can be
omitted. This parameter is needed to create the mail session for the Human
Task Manager to send notification mails.
-mailServerName mailServerName
Where mailServerName is the host name of the mail server to be used by the
Human Task Manager to send notification mails. It is needed when configuring
the mail session. If this parameter is set to an empty value, the mail session
configuration will be skipped. The default value is the fully qualified host
name of the local host.
-mailUser mailUserID
Where mailUserID is the user ID to access the mail server. This parameter is
only needed if the mail server requires authentication. Otherwise, it can be
omitted. This parameter is needed to create the mail session for the Human
Task Manager to send notification mails. The default value is empty, which is
only appropriate if no authentication is required.
-maxListEntries maximum
Where maximum is the maximum number of results that the Business Process
Choreographer Explorer will return for a query. The default is 10000.
-medbPwd MEDBPassword
Where MEDBPassword is the password for the user ID that is provided for the
medbUser parameter. This parameter has no default value.
-medbUser MEDBUserID
Where MEDBUserID is the user ID to access the messaging engine database.
The default value for this parameter is the value of the dbUser parameter. The
parameter is only required when the meStoreType parameter is set to
DATASTORE, and the messaging engine database is not accessed through the
Derby Embedded JDBC provider.
-meStoreType { FILESTORE | DATASTORE }
Set the message store type for the Business Process Choreographer message
Chapter 4. Configuring Business Process Choreographer

165

engine. If the mqDataSource parameter is supplied, this parameter is set to


DATASTORE. If the Service Component Architecture (SCA) is using FILESTORE,
this parameter is set to FILESTORE. FILESTORE is not supported in Network
Deployment environments. If mqDataSource is not set, and the SCA uses
DATASTORE as its message store type, then the SCA message engine database
settings, such as database type, JDBC provider, and database server, are
inherited. In this case, a separate database schema has to be set though (see
mqSchemaName below), and the mqCreateTables flag can be overwritten as
well.
-monitorBFMGroups groupList
Where groupList is the list of names of groups, from the user registry, to which
to map the BPESystemMonitor J2EE role. The separator character is the vertical
line (|). This property is needed to install the business process container. This
parameter has no default value. Either or both monitorBFMUsers or
monitorBFMGroups must be set.
-monitorBFMUsers userList
Where userList is the list of names of users, from the user registry, to which to
map the BPESystemMonitor J2EE role. The separator character is the vertical
line (|). This property is needed to install the business process container. This
parameter has no default value. Either or both monitorBFMUsers or
monitorBFMGroups must be set.
-monitorHTMGroups groupList
Where groupList is the list of names of groups, from the user registry, to which
to map the TaskSystemMonitor J2EE role. The separator character is the
vertical line (|). This property is needed to install the human task container.
This parameter has no default value. Either or both monitorHTMUsers or
monitorHTMGroups must be set.
-monitorHTMUsers userList
Where userList is the list of names of users, from the user registry, to which to
map the TaskSystemMonitor J2EE role. The separator character is the vertical
line (|). This property is needed to install the human task container. This
parameter has no default value. Either or both monitorHTMUsers or
monitorHTMGroups must be set.
-mqType JMSProviderType
Where JMSProviderType is the type of Java Message Service (JMS) provider to
use for Business Process Choreographer. It is used to create the queue manager
and the queues, the listener ports or ActivationSpecs, and the queue connection
factories.
Where JMSProviderType is one of the following values:
WPM For default messaging (WebSphere Platform Messaging). This option is
always available.
MQSeries
For WebSphere MQ. This option requires that the product WebSphere
MQ is installed. Using this value is deprecated.
-mqClusterName mqClusterName
Where mqClusterName is the name of the WebSphere MQ cluster that the queue
manager will join. This parameter is optional. The default value is MQCluster.
This option only has an effect if the parameter mqType has the value MQSeries,
which is deprecated.
-mqCreateTables { true | false}
This Boolean parameter controls whether the default JMS provider

166

Business Process Choreographer

automatically creates its tables in the message engine database upon the first
connection. If this flag is set to true for the Service Component Architecture
(SCA), this parameter is also set to true. If this flag is set to false for the SCA,
this parameter is also set to false. This option is only used when the mqType
option is set to WPM and meStoreType is set to DATASTORE.
-mqDataSource datasourceName
This optional parameter can be used to overwrite the default behavior of
inheriting the message store settings from the underlying SCA configuration
(see the description for the meStoreType parameter). Where datasourceName is
the JNDI name of a data source that is already defined on the Business Process
Choreographer destination location, that is, the server or cluster where the
SCA message engines are defined.
-mqHome MQInstallationDirectory
Where MQInstallationDirectory is the installation directory of WebSphere MQ.
This is used to create the queue manager and the queues (Windows platforms
only) and for creating the listener ports and the queue connection factories. If
the WebSphere variable MQ_INSTALL_ROOT is set, its value is used, and is
not modified. This option only has an effect if the parameter mqType has the
value MQSeries, which is deprecated.
If MQ_INSTALL_ROOT is not set, the default value used for
MQInstallationDirectory depends on the platform:
Windows platforms:
current_drive\Program Files\IBM\WebSphere MQ
AIX:

/usr/mqm

i5/OS: /QIBM/ProdData/mqm
Solaris, HP-UX, and Linux:
/opt/mqm
-mqPwd JMSProviderPassword
Where JMSProviderPassword is the password for the user ID provided for
mqUser. This parameter has no default value.
-mqSchemaName mqSchemaName
Where mqSchemaName is the name of the database schema for the default JMS
providers messaging engine. The default value is BPEME. This option is only
used when meStoreType is set to DATASTORE.
-mqUser JMSProviderUserID
Where JMSProviderUserID is the user ID to access the JMS provider.
v If mqType has the value WPM, this parameter is used to authenticate against
the Business Process Choreographer SI bus; the default value is the currently
logged on user.
v If mqType has the value MQSeries, this parameter is used on Linux and
UNIX platforms to create the queue manager and the queues. The default
value for JMSProviderUserID is mqm.
-node nodeName
Where nodeName is the name of the node where Business Process
Choreographer will be configured. If you have only one node and exactly one
server, this parameter is optional.
-password userPassword
If WebSphere administrative security is enabled, you must provide the

Chapter 4. Configuring Business Process Choreographer

167

password for the user ID userName. This is a wsadmin parameter, if you do not
specify it, you will not be prompted for it.
-profileName profileName
Where profileName is the name of a user-defined profile. Specify this option if
you are not configuring the default profile. This is a wsadmin parameter, if
you do not specify it, you will not be prompted for it.
-precompileJSPs { no | yes }
Determines whether Java Server Pages (JSPs) will be precompiled, or not. The
default is no. Note that it is not possible to debug precompiled JSPs.
-qmNameGet getQueueManagerName
Where getQueueManagerName is the name of the queue manager for GET
requests. It is used to create the queue manager and the queues, and to create
the listener ports and the queue connection factories. It must not contain the character. The default value for getQueueManagerName is
BPC_nodeName_serverName. This option only has an effect if the parameter
mqType has the value MQSeries, which is deprecated.
-qmNamePut putQueueManagerName
Where putQueueManagerName is the queue manager name for PUT requests. It
is used only when the mqClusterName parameter has been set. It is used to
create the queue manager and the queues, and to create the listener ports and
the queue connection factories. It must not contain the - character, and it must
not be the same as the queue manager name specified for the qmNameGet
parameter. The default value for putQueueManagerName is
BPCC_nodeName_serverName.
-remoteCluster clusterName
Use this parameter, if you do not want to connect to the local Business Process
Choreographer configuration and you do not specify remoteNode and
remoteServer. If this parameter is not specified, it defaults to the value of the
-cluster parameter.
-remoteNode nodeName
Use this parameter and remoteServer if you do not want to connect to the local
Business Process Choreographer configuration. If this parameter is not
specified, it defaults to the value of the -node parameter.
-remoteServer serverName
Use this parameter and remoteNode if you do not want to connect to the local
Business Process Choreographer configuration. If this parameter is not
specified, it defaults to the value of the -server parameter.
-restAPIBFM restAPIURL
Where restAPIURLis the URL for the Business Flow Manager REST API, which
is needed to support the graphical process widget for the Business Process
Choreographer Explorer. On a standalone server, the default is computed, for
example, http://localhost:9080/rest/bpm/bfm. In a network deployment
environment there is no default value.
-restAPIHTM restAPIURL
Where restAPIURL is the URL for the Human Task Manager REST API, which
is needed to support the graphical process widget for the Business Process
Choreographer Explorer. On a standalone server, the default is computed, for
example, http://localhost:9080/rest/bpm/htm. In a network deployment
environment there is no default value.

168

Business Process Choreographer

-server serverName
Where serverName is the name of the server where Business Process
Choreographer will be configured. If you have only one node and exactly one
server, this parameter is optional.
-user userName
If WebSphere administrative security is enabled, you must provide a user ID
for authentication. This is a wsadmin parameter, if you do not specify it, you
will not be prompted for it.

Example: Running the configuration script interactively


This example, illustrates running the bpeconfig.jacl script to install and configure a
business process container that uses an existing DB2 database, a human task
container, and a Business Process Choreographer Explorer.
Restriction: When run interactively, this script cannot configure Business Process
Choreographer Observer, nor the necessary event collector application. If you want
to use Business Process Choreographer Observer, you must perform Configuring
the Business Process Choreographer Observer on page 207.
1. On the server, or for network deployment, on the deployment manager, start
the script:
v On Linux and UNIX platforms, enter the command:
install_root/bin/wsadmin.sh
-f install_root/ProcessChoreographer/config/bpeconfig.jacl
( [-user userName][-password password]|[-conntype NONE])
[-profileName profileName]

v On i5/OS platforms, enter the command:


install_root/bin/wsadmin
-f install_root/ProcessChoreographer/config/bpeconfig.jacl
( [-user userName][-password password]|[-conntype NONE])
[-profileName profileName]

v On Windows platforms, enter the command:


install_root\bin\wsadmin.bat
-f install_root\ProcessChoreographer\config\bpeconfig.jacl
( [-user userName][-password password]|[-conntype NONE])
[-profileName profileName]

2. Interactively enter responses to the questions that are displayed:


a. In a network deployment environment, you will be offered a server, or
cluster, to configure in. If it is not the correct server, or cluster, enter No to
be offered the next server, or cluster. If it is the correct server, or cluster,
enter Yes.
b. For the question Install the business process container?, enter Yes.
c. For the question User(s) to add to role BPESystemAdministrator, enter
the user IDs for the users who will perform the role of business process
administrator.
d. For the question Group(s) to add to role BPESystemAdministrator, enter
the groups from the domain user registry that are mapped onto the role of
business process administrator.
e. For the question User(s) to add to role BPESystemMonitor, enter the user
IDs for the users who will perform the role of business process monitor.
f. For the question Group(s) to add to role BPESystemMonitor, enter the
groups from the domain user registry that are mapped onto the role of
business process monitor.
Chapter 4. Configuring Business Process Choreographer

169

g. For the question Run-as UserId for role JMSAPIUser, enter the run-as user
ID that will be used for the JMSAPIUser role.
h. Enter the password for the run-as user ID.
i. For the question Use WebSphere default messaging or WebSphere MQ
[WPM/MQSeries]?, select the JMS provider that you want to use.
j. Enter the following:
1) For the question Virtual Host for the SCA Web Service
[default_host]: , press Enter to accept the default value default_host
for the Service Component Architecture (SCA) Web server virtual host.
2) For the question Context root for the SCA Web Service
[/BFMIF_PNODE_server1]:, press Enter to accept the default value
BFMIF_nodeName_serverName.
3) For the question Context root for the REST API [/rest/bpm/bfm]:,
press Enter to accept the default value /rest/bpm/bfm.
k. For the question Create the DataSource for the Process Choreographer
database?, enter Yes.
l. For the question Create DataSource for a Derby, a DB2, an Informix, an
Oracle, or an SQL Server database [Derby/DB2/zOS-DB2/iSeries-DB2/
Informix/Oracle/MSSQL]?, for this example, enter DB2. Selecting a different
database results in other database-specific questions.
m. Enter the database name.
n. At the Database schema name (may be empty) prompt, hit Enter to use the
implicit schema qualifier.
o. For the question Universal or CLI?, hit Enter to select the default Universal
JDBC driver
p. For the question DB2 User ID, enter the user ID to access the database.
q. Enter the password for the database user ID.
r. For the question Database server name (may be empty, set to use the
type 2 driver), enter the name of the server that hosts the database.
s. For the question Database server port, enter the database server port, for
example, 50000.
t. At the JDBC driver directory on [yourHost] prompt, enter the directory
where the DB2 JDBC driver JAR files are located.
u. For the question Create the Process Choreographer database objects?, if
your currently logged on user ID has sufficient authority to create the
database, and DB2 has been set up in your current environment (for
example, the db2 exeuctable is on the PATH), you can enter Yes, otherwise,
if your currently logged on user ID does not have sufficient authority to
create the database, enter No.
If the answer is Yes:
1) For the question DB2 tablespace directory (may be empty) hit Enter to
leave it empty.
2) For the question Is BPEDB an existing database (the Process
Choreographer schema must not yet exist) prompt according to your
environment.
v. If you get the question User ID for access to Process Choreographer SI
bus, enter the user ID to use to access the default JMS provider.
w. Enter the password for the SI bus authentication user ID.
x. For the question Install the task container?, enter Yes.

170

Business Process Choreographer

y. For the question User(s) to add to role TaskSystemAdministrator, enter


the user IDs for the users who will perform the role of task administrator.
z. For the question Group(s) to add to role TaskSystemAdministrator, enter
the groups from the domain user registry that are mapped onto the role of
task administrator.
aa. For the question User(s) to add to role TaskSystemMonitor, enter the
user IDs for the users who will perform the role of task monitor.
ab. For the question Run-as UserID for role EscalationUser, enter the run-as
user ID for the role of escalation user, for example db2admin.
ac. Enter the password for the escalation user ID. This prompt will be hidden
if you used the same user ID as for step 2g on page 170.
ad. For the question Context root for the SCA Web Service
[/HTMIF_PNODE_server1]:, press Enter to accept the default value
HTMIF_nodeName_serverName.
ae. For the question Context root for the REST API [/rest/bpm/htm]:, press
Enter to accept the default value /rest/bpm/htm.
af. For the question Create the mail notification session for the human
task manager?, enter No if you do not want to create the mail notification
session for the Human Task Manager. Otherwise, enter Yes, and specify the
mail transport host. Optionally, you can specify the user ID and password.
ag. For the question Context root for the Business Process Choreographer
Explorer [/bpc]: , enter the context root for Business Process
Choreographer Explorer or press Enter to use the default value /bpc.
ah. For the question Install the Business Process Choreographer Explorer?,
enter Yes to install Business Process Choreographer Explorer, then for the
question Precompile JSPs?, enter Yes if you want Java Server Pages (JSPs)
to be precompiled, otherwise enter No. For a remote Business Process
Choreographer Explorer, for the question Node of Process Choreographer
to connect to [PNODE]: enter the name of the Business Process
Choreographer node to connect to, and for the question Server of Process
Choreographer to connect to [server1]: enter the name of the Business
Process Choreographer server to connect to or press Enter to accept the
default.
ai. For the question Maximum number of list entries for the Process
Choreographer Explorer , press Enter to use the default value 10000.
aj. The following reminder is displayed:
******************************************************************************
* NOTE: The Process Choreographer REST API URLs are needed by the
* Process Choreographer Explorers graphical process widget.
* In an ND environment, it is not possible to compute default values for them.
******************************************************************************

ak. For the question URL for the Business Flow Manager REST API , press
Enter to use the default value http://host_name:9080/rest/bpm/bfm.
al. For the question URL for the Human Task Manager REST API , press Enter to
use the default value http://host_name:9080/rest/bpm/htm.
am. Various information is displayed, for example providing the URL of the
Business Process Choreographer Explorer. For example:
******************************************************************************
* NOTE: The Process Choreographer URL will be used by the
* Human Task Manager on server server1 of node viennaNode01
* to link to this Explorer instance. Set an empty URL to not create this link.
******************************************************************************
URL for this Process Choreographer Explorer [http://host_name:9080/bpc]:

Enter the URL for this Business Process Choreographer Explorer instance,
or press Enter to accept the default.
Chapter 4. Configuring Business Process Choreographer

171

an. A reminder is displayed about where to find the script files that you can
use to configure Business Process Choreographer Observer.
To interactively configure the EventCollector, please use the script
setupEventCollector located in install_root\ProcessChoreographer\config.
To interactively configure the Observer, please use the script
setupObserver located in install_root\ProcessChoreographer\config.

3. In case of problems, check the log files.

Log files
If you have problems creating the configuration using the bpeconfig.jacl script file,
check the following log files:
v bpeconfig.log
v wsadmin.traceout
Both files can be found in the logs directory for your profile:
v On Linux, UNIX, and i5/OS platforms: In the directory profile_root/logs
v On Windows platforms: In the directory profile_root\logs
If you run the script in connected mode, also check the files SystemOut.log and
SystemErr.log that can be found in the subdirectory of the logs directory that is
named after the application server or deployment manager that the wsadmin
scripting client connected to.
Related tasks
Using the bpeconfig.jacl script to configure Business Process Choreographer
on page 150
Describes how to use the bpeconfig.jacl script to configure Business Process
Choreographer and all the necessary resources on a given server or cluster.

Creating the queue manager and queues for Business


Process Choreographer
This describes how to create the WebSphere MQ queue manager and queues.
Before you begin
WebSphere MQ must already be installed.
Note: Support for WebSphere MQ is deprecated.
About this task
If you are using WebSphere MQ as an external Java Message Service (JMS)
provider, you must create the queue manager and queues.
Procedure
1. Optional: If you are creating a production system, plan which disk drives the
queue manager will use. Using default locations for persistent queue data and
WebSphere MQ logs can have a negative impact on the performance of the
queue manager. Consider changing these locations according to
recommendations in the WebSphere MQ documentation.
2. If you are not creating a WebSphere MQ cluster setup, perform the following
actions:

172

Business Process Choreographer

a. Make sure that your user ID has the authority to create WebSphere MQ
queues.
b. Create the queue manager and queues: On Windows platforms, enter:
cd install_root\ProcessChoreographer\config
createQueues.bat queueManager

On UNIX and Linux platforms, enter:


cd install_root/ProcessChoreographer/config
createQueues.sh queueManager

On i5/OS platforms, enter:


cd install_root/ProcessChoreographer/config
createQueues queueManager

where queueManager is the name of an existing queue manager, or the name


to give to a new queue manager. If the named queue manager already
exists, it is used to create the queues. If the queue manager does not exist, it
is created and started before the default queues are created.
3. If you are creating a WebSphere cluster setup that uses a WebSphere MQ
cluster, only perform Creating clustered queue managers and queues.
4. If you are creating a WebSphere cluster setup that uses a central queue
manager, perform the following actions:
a. Copy the create queues script file from the config subdirectory of the
ProcessChoreographer directory on the server that hosts WebSphere Process
Server machine to the server that hosts the central queue manager:
v If your central queue manager is on a Windows workstation, copy the
file: createQueues.bat
v If your central queue manager is on a UNIX or Linux server, copy the
file: createQueues.sh
v If your central queue manager is on an i5/OS server, copy the file:
createQueues
b. On the server that hosts the queue manager, make sure that WebSphere MQ
is installed, and that your user ID has the authority to create WebSphere
MQ queues.
c. Create the queue manager and queues: On Windows platforms, enter:
cd install_root\ProcessChoreographer\config
createQueues.bat queueManager

On Linux and UNIX platforms, enter:


cd install_root/ProcessChoreographer/config
createQueues.sh queueManager

On i5/OS platforms, enter:


cd install_root/ProcessChoreographer/config
createQueues queueManager

where queueManager is the name to give the new queue manager.


d. Add a listener for the new queue manager:
On Windows platforms, enter:
runmqlsr -t tcp -p port -m queueManager

On Linux, UNIX, and i5/OS platforms, enter:


runmqlsr -t tcp -p port -m queueManager &
Chapter 4. Configuring Business Process Choreographer

173

Where port is the port on which the listener listens.


Results
The queue manager and queues exist.

Creating clustered queue managers and queues for Business


Process Choreographer
If you are creating a WebSphere cluster setup of Business Process Choreographer
using a WebSphere MQ cluster, you must create the queue managers, queues,
cluster, repositories, channels, and listeners.
Procedure
1. If your WebSphere cluster consists of UNIX nodes, perform the following
actions on each node:
a. Make sure that your user ID has the authority to create WebSphere MQ
queues.
b. Create the get and put queue managers, make them members of the
WebSphere MQ cluster, and create the queues by entering the commands:
cd install_root/ProcessChoreographer/config
createQueues.sh getQueueManager clusterName putQueueManager

where:
getQueueManager
The unique name to give to the get queue manager. This queue
manager hosts all of the local queues.
clusterName
The name of the WebSphere MQ cluster of which all the queue
managers are a member.
putQueueManager
The unique name for the put queue manager. This queue manager
hosts no queues, which ensures that messages are distributed across
all the get queues.
If the queue managers already exist, they are used. If the queue managers
do not exist, they are created and used.
c. Start the WebSphere MQ command processor by entering the command:
runmqsc getQueueManager

d. For complex setups, it is recommended to enable remote administration of


the queue manager by entering the following MQ command:
DEFINE CHANNEL(SYSTEM.ADMIN.SVRCONN) TYPE(CHLTYPE)

e. If this queue manager is to be a repository for the WebSphere MQ cluster


enter the MQ command:
ALTER QMGR REPOS(clusterName) REPOSNL( )

f. Define a sender and a receiver channel for the queue manager to each
repository that is not hosted on this server, by entering the following MQ
commands. For each cluster receiver channel:
DEFINE CHANNEL(TO.repositoryQueueManager.TCP) +
CHLTYPE(CLUSRCVR) +
CLUSTER(clusterName) +
CLUSNL( ) +
CONNAME(repositoryIP-Address(port)) +
DESCR(Cluster receiver channel at repositoryQueueManager TCPIP) +
MAXMSGL(4194304) +
TRPTYPE(TCP) +
MCAUSER(principal) +
REPLACE

174

Business Process Choreographer

For each cluster sender channel:


DEFINE CHANNEL(TO.repositoryQueueManager.TCP) +
CHLTYPE(CLUSSDR) +
CONNAME(repositoryIP-Address(port)) +
CLUSTER(clusterName) +
CLUSNL( ) +
DESCR(Cluster sender channel to repositoryQueueManager TCPIP) +
MAXMSGL(4194304) +
TRPTYPE(TCP) +
MCAUSER(targetPrincipal) +
REPLACE +
NPMSPEED (NORMAL)

where:
repositoryQueueManager
The name of the queue manager hosting a repository.
clusterName
The name of the WebSphere MQ cluster of which all the queue
managers are a member.
repositoryIP-Address
The IP address of the node where the repository queue manager
resides.
port
The IP port that the repository queue manager is using.
principal, targetPrincipal
The MCAUSER to use for the receive and send channels. For more
information about this value refer to the WebSphere MQ
documentation.
g. For each queue manager, start a listener by entering the MQ command:
runmqlsr -t tcp -p port -m QueueManager

2. If your WebSphere cluster consists of Windows nodes, perform the following


actions on each node:
a. Make sure that your user ID has the authority to create WebSphere MQ
queues.
b. Create the get queue manager, make it a member of the WebSphere MQ
cluster, and create the queues by entering the commands:
cd install_root\ProcessChoreographer\config
createQueues.bat getQueueManager clusterName putQueueManager

where:
getQueueManager
The unique name to give to the get queue manager. This queue
manager hosts all of the local queues.
clusterName
The name of the WebSphere MQ cluster of which all the queue
managers are a member.
putQueueManager
The unique name for the put queue manager. This queue manager
hosts no queues, which ensures that messages are distributed across
all the get queues.
If the queues already exist they are used. If the queues do not exist, they are
created and used.
c. Start the WebSphere MQ command processor by entering the command:
runmqsc queueManager

d. For complex setups, it is recommended that you enable remote


administration of the queue manager by entering the following MQ
command:
DEFINE CHANNEL(SYSTEM.ADMIN.SVRCONN) TYPE(CHLTYPE)
Chapter 4. Configuring Business Process Choreographer

175

e. If this queue manager is to be a repository for the WebSphere MQ cluster


enter the MQ command:
ALTER QMGR REPOS(clusterName) REPOSNL( )

f. Define a sender and a receiver channel for the queue manager to each
repository that is not hosted on this server, by entering the following MQ
commands. For each cluster receiver channel:
DEFINE CHANNEL(TO.repositoryQueueManager.TCP) +
CHLTYPE(CLUSRCVR) +
CLUSTER(clusterName) +
CLUSNL( ) +
CONNAME(repositoryIP-Address(port)) +
DESCR(Cluster receiver channel at repositoryQueueManager TCPIP) +
MAXMSGL(4194304) +
TRPTYPE(TCP) +
MCAUSER(principal) +
REPLACE

For each cluster sender channel:


DEFINE CHANNEL(TO.repositoryQueueManager.TCP) +
CHLTYPE(CLUSSDR) +
CONNAME(repositoryIP-Address(port)) +
CLUSTER(clusterName) +
CLUSNL( ) +
DESCR(Cluster sender channel to repositoryQueueManager TCPIP) +
MAXMSGL(4194304) +
TRPTYPE(TCP) +
MCAUSER(principal) +
REPLACE +
NPMSPEED (NORMAL)

where:
repositoryQueueManager
The name of the queue manager hosting a repository.
clusterName
The name of the WebSphere MQ cluster to which all the queue
managers are a member.
repositoryIP-Address
The IP address of the node where the repository queue manager
resides.
port
The IP port that the repository queue manager is using.
principal
The MCAUSER to use. For more information about this value, refer
to the WebSphere MQ documentation.
g. For each queue manager, start a listener by entering the MQ command:
runmqlsr -t tcp -p port -m QueueManager

3. Optional: To verify the status of the channels on a server, enter the MQ


command:
display chstatus(*)

Results
The queue managers, queues, cluster, repositories, channels, and listeners exist.

Using a generated SQL script to create the database schema


for Business Process Choreographer
When you configure Business Process Choreographer, an SQL script is generated
that creates the database objects for Business Process Choreographer.

176

Business Process Choreographer

Before you begin


You have used the administrative console or the bpeconfig.jacl script to configure
Business Process Choreographer. If you used the bpeconfig.jacl script to configure
Business Process Choreographer, either you used the -createDB no option to defer
creating the database objects, or the bpeconfig.jacl script failed to create the
database.
About this task
All the relevant configuration parameters that you provided when configuring
Business Process Choreographer have been substituted in the generated SQL file.
You either want the database for a high-performance Business Process
Choreographer configuration, or your database administrator must create the
database for you, or both.
Procedure
1. Locate the generated createSchema.sql SQL script.
v If you configured Business Process Choreographer in a network deployment
environment using the administrative console or by running the
bpeconfig.jacl script in connected mode, the createSchema.sql script file will
be generated on the node of the deployment manager.
v If you configured Business Process Choreographer on a standalone server
using the administrative console or by running the bpeconfig.jacl script in
connected mode, the createSchema.sql script file will be generated on the
node where you invoked wsadmin.
v If you configured Business Process Choreographer by running the
bpeconfig.jacl script in disconnected mode, the createSchema.sql script file
will be generated on the node of the standalone server.
Option

Description

For Linux and UNIX

v If you specified a schema qualifier, the


generated script is: profile_root/
dbscripts/ProcessChoreographer/
database_type/database_name/
database_schema/createSchema.sql.
v If you did not specify a schema qualifier,
the generated script is:
profile_root/dbscripts/
ProcessChoreographer/database_type/
database_name/createSchema.sql.

For i5/OS

The generated script is: profile_root/


dbscripts/ProcessChoreographer/
database_type/collection_name/
createSchema.sql.

Chapter 4. Configuring Business Process Choreographer

177

Option

Description

For Windows

v If you specified a schema qualifier, the


generated script is: profile_root\
dbscripts\ProcessChoreographer\
database_type\database_name\
database_schema\createSchema.sql
v If you did not specify a schema qualifier,
the generated script is:
profile_root\dbscripts\
ProcessChoreographer\database_type\
database_name\createSchema.sql
Note: For SQL Server, there is also a version
named createSchemaUnicode.sql, which you
should use if your database is configured for
Unicode.

For z/OS

There is an ASCII SQL script, named


createSchema.sql, and an equivalent
EBCDIC DDL script, named
createSchema.ddl:
v If you specified a schema qualifier, both
files are located in profile_root/
dbscripts/ProcessChoreographer/
database_type/database_name/
database_schema
v If you did not specify a schema qualifier,
both files are located in
profile_root/dbscripts/
ProcessChoreographer/database_type/
database_name

Where:
database_type
is one of the following:
v DB2
v DB2zOSV8
v DB2zOSV9
v Db2iSeries
v Derby
v Informix
v Oracle
v SQLServer
database_name
is the name of your database.
database_schema
is the name of the schema, if you are using one.
collection_name
is the name of the collection; only for DB2 on iSeries.
2. If the database does not yet exist, get your database administrator to create the
database and user IDs according to the values you planned in Planning the
BPEDB database on page 117 and Planning security, user IDs, and
authorizations on page 110.
Note: This step is not necessary if your database is one of the following,
because the generated script will create the database instance:

178

Business Process Choreographer

v Derby Embedded
v Derby Network and the database server is running
v DB2 on iSeries
v DB2 for Linux, UNIX, or Windows local database
3. If the database is remote, copy the generated script to the database host. If you
are not authorized to perform this, give your database administrator a copy of
the script and discuss your requirements with her.
4. You or your database administrator can customize the SQL script:
a. If you used the administrative console to configure Business Process
Choreographer, substitute actual values for the following placeholders:
v For DB2 on z/OS: Replace @STOGRP@ with the storage group name, the
default value is SYSDEFLT.
v Replace @location@ (or for Oracle, replace &1) with the tablespace
directory.
b. For a high-performance system specify the allocation of disks and table
spaces that you planned in step 5 on page 119 of Planning the BPEDB
database on page 117.
5. Run the SQL script on the database host using one of the following commands:
Option

Description

For DB2 on Linux, UNIX, or Windows

db2 -tf createSchema.sql

For DB2 on iSeries

db2 -tf createSchema.sql

For DB2 on z/OS

For the ASCII version:


db2 -tf createSchema.sql
For the EBCDIC version:
db2 -tf createSchema.ddl

For a Derby database

java -Dij.protocol=jdbc:derby:
-Dij.database=database_name
org.apache.derby.tools.ij
createSchema.sql

For an Informix database

dbaccess database_name createSchema.sql

For an Oracle database

sqlplus userID/password
@database_name@createSchema.sql

For an SQL Server database

For an ASCII database:


sqlcmd -U
-P
-d
-i

userID
password
database_name
createSchema.sql

For a Unicode database:


sqlcmd -U
-P
-d
-i

userID
password
database_name
createSchemaUnicode.sql

6. For all existing Business Process Choreographer configurations, configure Java


Database Connectivity (JDBC) to access the database remotely: Perform the
following steps:
v On each node that hosts a member of the cluster where you configured
Business Process Choreographer.
v On any server that runs Business Process Choreographer.
Chapter 4. Configuring Business Process Choreographer

179

a. If the database server is different to the Business Process Choreographer


server, install a suitable type-2 database client or type-4 JDBC driver on the
server that hosts the application server.
b. If you are using a type-2 JDBC driver, make the new database known to the
database client. The database must be catalogued and accessible through an
alias name.If you are using a type-2 JDBC driver, make the new database
known to the database client by performing the following:
For Derby
This step does not apply because only the type-4 JDBC provider is
supported.
For DB2 Universal Database
The database must be cataloged and accessible through an alias
name.
For DB2 for iSeries
The database must be cataloged and accessible through an alias
name.
For DB2 for z/OS
The database must be cataloged and accessible through an alias
name.
For Informix Dynamic Server
This step does not apply because only the type-4 JDBC provider is
supported.
For Microsoft SQL Server
This step does not apply because only type-4 JDBC providers are
supported.
For Oracle
The TCP net service name (TNS) is used to access the database.
c. Using the administrative console, test the connection to the database.
1) Click Resources JDBC Business Integration Data Sources
2) If necessary, select a different scope and click Apply.
Note: For clustered Business Process Choreographer configurations, the
data source is defined at the cluster level. For non-clustered
configurations, the data source is defined at the server level.
3) Locate and select the data source with the JNDI name jdbc/BPEDB.
4) Click Test connection.
5) You should see a message indicating that the test connection was
successful.
Results
The Business Process Choreographer database exists.

Using SQL scripts to create the database for Business Process


Choreographer
You might choose to create the database for Business Process Choreographer
manually before you configure Business Process Choreographer, or even before you
have installed the product.
Before you begin
You have performed Planning the BPEDB database on page 117.

180

Business Process Choreographer

About this task


Your organization might require that databases be created by a separate database
administrator. If you use the administrative console or the bpeconfig.jacl script to
configure Business Process Choreographer, customized SQL scripts are generated
that you can give to your DBA to create the BPEDB database. However, if you
want to create the database before configuring Business Process Choreographer, or
even before product installation, your DBA must use the non-customized SQL
scripts. This topic describes how to use the non-customized SQL scripts, which are
available on the product media.
Procedure
On the server that hosts the database, create the database according to the
description for your database system.
v Creating a Derby database for Business Process Choreographer.
v Creating a DB2 for i5/OS database for Business Process Choreographer on
page 182.
v Creating a DB2 for Linux, UNIX, and Windows database for Business Process
Choreographer on page 183.
v Creating a DB2 for z/OS database for Business Process Choreographer on
page 185.
v Creating an Informix Dynamic Server database for Business Process
Choreographer on page 187.
v Creating a Microsoft SQL Server database for Business Process Choreographer
on page 189.
v Creating an Oracle database for Business Process Choreographer on page 190.
Results
The Business Process Choreographer database exists.

Creating a Derby database for Business Process


Choreographer
Only use this task if you want to create a Derby database for Business Process
Choreographer before you configure Business Process Choreographer, or before
you have installed the product.
Before you begin
You completed Planning the BPEDB database on page 117. The Derby database
is installed with the WebSphere Process Server. However, if you want to create the
database before installing the product, you must already have a Derby installation
on your database server.
About this task
To create a Derby database named BPEDB, perform the following actions:
Procedure
1. If you want to create a Derby Network Server database, rather than a Derby
Embedded database, make sure that the for Derby Network Server is running,
and that you have planned to use the Derby Network Server JDBC provider.
Chapter 4. Configuring Business Process Choreographer

181

2. Create the parent directory for the database by performing one of the
following:
v To prepare to create the database in the default location, manually create a
databases subdirectory in the appropriate profile directory.
On Linux, UNIX, and i5/OS platforms create profile_root/databases.
On Windows platforms, create profile_root\databases.
Change to the new directory.
v To prepare to create a database location other than the default location,
change to the directory where you want the new database created.
3. Copy the database creation script to the directory that you created in step 2.
The script is located in the following directories:
v On Linux, UNIX, and i5/OS platforms:
Location on the product media: media_root or extract_directory/dbscripts/
ProcessChoreographer/Derby/createDatabase.sql
Location after installation: install_root/dbscripts/ProcessChoreographer/
Derby/createDatabase.sql
v On Windows platforms:
Location on the product media: media_root or extract_directory\dbscripts\
ProcessChoreographer\Derby\createDatabase.sql
Location after installation: install_root\dbscripts\ProcessChoreographer\
Derby\createDatabase.sql
4. Customize your copy of the database creation script, createDatabase.sql,
according to the instructions in the header. You must include the name of the
database. On Windows platforms, avoid using the Notepad editor, as it does
not display the file in a readable format.
5. Create the database. From the directory where the database is to be created, run
your customized version of the database creation script file createDatabase.sql
as described in the header.
Results
The database for Business Process Choreographer exists.

Creating a DB2 for i5/OS database for Business Process


Choreographer
Only use this task if you want to create the DB2 for i5/OS database schema for
Business Process Choreographer before you configure Business Process
Choreographer, or before you have installed the product.
Before you begin
You completed Planning the BPEDB database on page 117.
Procedure
1. On the machine that hosts the database: If no collection exists for the user ID
that owns the database, create a collection.
2. Copy the create schema script to the machine that hosts the database. The
script is located in the following directories:
v On Linux, UNIX, and i5/OS platforms:

182

Business Process Choreographer

Location on the product media: media_root or extract_directory/dbscripts/


ProcessChoreographer/DB2iSeries/createSchema.sql
Location after installation: install_root/dbscripts/ProcessChoreographer/
DB2iSeries/createSchema.sql
v On Windows platforms:
Location on the product media: media_root or extract_directory\dbscripts\
ProcessChoreographer\DB2iSeries\createSchema.sql
Location after installation: install_root\dbscripts\ProcessChoreographer\
DB2iSeries\createSchema.sql
3. Customize a copy of the SQL file createSchema.sql according to the values you
planned in Planning the BPEDB database on page 117, Planning security,
user IDs, and authorizations on page 110, and the instructions in the header of
the file.
4. Create the database objects. In a qshell environment, run your customized
script. For example, if the script is in your current directory, enter the
command:
db2 -tf createSchema.sql

5. If the database is remote from the Business Process Choreographer


configuration, plan to use the Toolbox JDBC driver. Copy the JAR file
/QIBM/ProdData/HTTP/Public/jt400/lib/jt400.jar from the database host to
the WebSphere Process Server.
6. If the database is local to the Business Process Choreographer configuration,
use the Native JDBC driver. Make sure that your classpath includes
/QIBM/ProdData/Java400/ext/db2_classes.jar.
Results
The DB2 for i5/OS schema for Business Process Choreographer exists.

Creating a DB2 for Linux, UNIX, and Windows database for


Business Process Choreographer
Only use this task if you want to create a DB2 database for Business Process
Choreographer before you configure Business Process Choreographer, or before
you have installed the product.
Before you begin
You completed Planning the BPEDB database on page 117.
Procedure
1. Install DB2 on the server that hosts the database.
2. Install a DB2 client on all remote application servers that use a type-2 Java
Database Connectivity (JDBC) driver to access the database.
3. Copy all the Business Process Choreographer database SQL script files to the
server that hosts the database. The scripts are located in the following
directories:
v On Linux, and UNIX platforms:
Location on the product media: media_root or extract_directory/dbscripts/
ProcessChoreographer/DB2
Location after installation: install_root/dbscripts/ProcessChoreographer/
DB2
Chapter 4. Configuring Business Process Choreographer

183

v On Windows platforms:
Location on the product media: media_root or extract_directory\dbscripts\
ProcessChoreographer\DB2
Location after installation: install_root\dbscripts\ProcessChoreographer\
DB2
4. Change to the directory where you copied the SQL scripts.
5. If you want to use an existing database, skip to step 10.
6. Create a DB2 instance on the database server.
7. If you have a Symmetric Multi-Processor (SMP) server check how many
processors can be used by DB2. Check your license:
v On AIX systems, enter the command:
/usr/opt/db2_08_01/adm/db2licm -l

v On other UNIX or Linux systems, enter the command:


/opt/IBM/db2/V8.1/adm/db2licm -l

If necessary, change the number of processor licenses using either the db2clim
command or the DB2 License Center.
8. Create a new database. Make sure that the database supports Unicode
(UTF-8). Without Unicode support, it cannot store all characters that can be
handled in Java code, and you can run into code page conversion problems
when a client uses an incompatible code page.
9. Optional: If you only want to create a non-production database, named
BPEDB, using default settings, for stand-alone development, evaluation, or
demonstration purposes:
a. Enter the following command:
db2 -tf createDatabase.sql

b. Skip to step 11 on page 185.


10. If the database is for a production system, create the table space and schema:
a. Make sure that you use a user ID that has administrator rights for the
database system.
b. Customize a copy of the createTablespace.sql table space creation script
according to the instructions in the files header, using the values that you
planned in Planning the BPEDB database on page 117.
c. Make sure that you have administrator rights for the database system. The
user ID that you use to create the schema must be the same one that you
specify when configuring the data source for Business Process
Choreographer.
d. Make sure that you are attached to the correct instance. Check the
DB2INSTANCE environment variable.
e. To connect to a database named databaseName, in the DB2 command-line
processor, enter the command:
db2 connect to databaseName

f. To create the table spaces, enter the command:


db2 -tf createTablespace.sql

Make sure that the script output contains no errors. If errors occur, you can
drop the table space using the dropTablespace.sql script.
g. Customize a copy of the createSchema.sql schema creation script according
to the instructions in the files header, using that values that you planned
in Planning the BPEDB database on page 117.

184

Business Process Choreographer

h. To create the schema (tables, indexes, and views) in the DB2 command-line
processor, enter the command:
db2 -tf createSchema.sql

Make sure that the script output contains no errors. If you want to drop
the schema, use the dropSchema.sql script.
Note: If you do not create the table space and schema now, you must use the
Create tables option later so that the default table space and schema will be
created the first time that Business Process Choreographer attempts to use the
database.
11. On each application server that remotely accesses the database:
a. Catalog the database by entering the command:
db2 catalog database databaseName as databaseAlias at node nodeName

For more information about cataloging a database refer to the DB2


documentation.
b. Verify that you can connect to the database by entering the commands:
db2 connect to databaseName user userID
db2 connect reset

Results
The database for Business Process Choreographer exists.

Creating a DB2 for z/OS database for Business Process


Choreographer
Only use this task if you want to create a DB2 for z/OS database for use by
WebSphere Process Server Business Process Choreographer that is running on a
Linux, UNIX, i5/OS, or Windows platform and have not yet configured Business
Process Choreographer, or you have not yet installed the product.
Before you begin
You completed Planning the BPEDB database on page 117.
About this task
This topic describes how to create a DB2 for z/OS database and, optionally, to
verify that it is reachable from the server that hosts the application server.
Procedure
1. Optional: You have already installed WebSphere Process Server on a UNIX,
Linux, Windows, or i5/OS server.
2. Copy all the Business Process Choreographer database script files to the z/OS
server that hosts the database. The scripts are located in the following
directories:
v On Linux, UNIX, i5/OS, and z/OS platforms:
Location on the product media: media_root or extract_directory/dbscripts/
ProcessChoreographer/database_type
Location after installation: install_root/dbscripts/ProcessChoreographer/
database_type
v On Windows platforms:
Chapter 4. Configuring Business Process Choreographer

185

Location on the product media: media_root or extract_directory\dbscripts\


ProcessChoreographer\database_type
Location after installation: install_root\dbscripts\ProcessChoreographer\
database_type
Where database_type is one of the following:
v DB2zOSV8
v DB2zOSV9
3. On the z/OS server that hosts the database:
a. Log on the native z/OS environment.
b. If multiple DB2 systems are installed, decide which subsystem you want to
use.
c. Make a note of the IP port to which the DB2 subsystem is listening.
d. Create the database and storage group. Perform one of the following:
v Use the DB2 administration menu to create a new database and storage
group.
v Edit a copy of the createDatabase.sql script file according to the
instructions in the header, using the values that you planned in Planning
the BPEDB database on page 117, then run the script. To run the script,
enter the command:
db2 -tf createDatabase.sql

e. Decide which user ID is used to connect to the database from the remote
server running WebSphere Process Server. Normally, for security reasons,
this user ID is not the one that you used to create the database.
f. Grant the user ID the rights to access the database and storage group. This
user ID must also have permission to create new tables for the database.
g. Decide if you want to create the tables and views in the schema of the
connected user ID or if you want to customize the schema qualifier. If a
single user ID accesses multiple databases with tables of the same name,
you must use different schema qualifiers to avoid name collisions.
h. Customize a copy of the createTablespace.sql table space creation script
according to what you planned in Planning the BPEDB database on page
117 and the instructions in the header. Replace @STOGRP@ with the storage
group name and replace @DBNAME@ with the database name (not the
subsystem name).
i. Run your customized version of the table space creation script. For example,
to run the script, enter the command:
db2 -tf createTablespace.sql

If you want to drop the table space, customize and run the
dropTablespace.sql script.
j. Edit the createSchema.sql create schema script according to what you
planned in Planning the BPEDB database on page 117 and the instructions
in the header.
1) Replace @STOGRP@ with the storage group name.
2) Replace @DBNAME@ with the database name (not the subsystem name).
3) Replace @SCHEMA@ with the schema qualifier or remove @SCHEMA@
(including the following dot) from the script. A custom schema qualifier
can only be used with the DB2 Universal JDBC driver.
k. Run your customized version of the create schema script. For example, to
run the script, enter the command:

186

Business Process Choreographer

db2 -tf createSchema.sql

If this script does not work, or if you want to remove the tables and views,
use the dropSchema.sql script to drop the schema, but replace @SCHEMA@
before running the script.
4. Optional: On any server that will host a WebSphere Process Server Business
Process Choreographer configuration:
a. Make sure that you have DB2 Connect Gateway installed. DB2 Connect
Gateway is part of the DB2 UDB ESE package, but you can also install it
separately.
b. Catalog the remote database using the following commands in a DB2
command line window:
catalog tcpip node zosnode remote host_name server IP_port ostype mvs
catalog database location as database_alias at node zosnode
authentication dcs
catalog dcs database database_alias parms ,,INTERRUPT_ENABLED

where
zosnode
is a local alias for the remote z/OS node.
host_name
is either the TCP/IP address or alias of the remote z/OS machine.
IP_port
is the port number where the DB2 subsystem is listening.
database_alias
is the local alias to access the remote database.
location
is the remote DB2 location name. To find out the location name, log on
to TSO and enter the following SQL query on the selected subsystem
using one of the available query tools.
select current server from sysibm.sysdummy1

c. Make sure that the sync point manager instance name is specified. Enter the
following commands:
db2 update dbm cfg using SPM_NAME host_name
db2 update dbm cfg using SPM_LOG_FILE_SZ log_file_size

d. Verify that you can establish a connection to the remote subsystem by


entering the following command:
db2 connect to database_alias user userid using password

Results
The database for Business Process Choreographer exists.

Creating an Informix Dynamic Server database for Business


Process Choreographer
Only use this task if you want to create an Informix Dynamic Server database for
Business Process Choreographer before you configure Business Process
Choreographer, or before you have installed the product.
Before you begin
You completed Planning the BPEDB database on page 117.
Chapter 4. Configuring Business Process Choreographer

187

Procedure
1. Install the Informix server on the computer that hosts the database.
2. Create an Informix server instance. Make sure that the following Informix
environment variables are set correctly:
v INFORMIXSERVER must point to the new instance
v ONCONFIG must point to the configuration file for the instance.
v The environment variables relating to Global Language Support (GLS) must
be set to Unicode (UTF-8) support, which is required to store all the
characters that can be handled in Java code.
For more details about the different environment variables, refer to the Informix
Dynamic Server documentation.
3. Copy and configure the Java Database Connectivity (JDBC) driver on all remote
application servers that use the database server.
4. Copy all the Business Process Choreographer database script files to the server
that hosts the database.
v On Linux, and UNIX platforms, copy all the SQL and SH files:
Location on the product media: media_root or extract_directory/dbscripts/
ProcessChoreographer/Informix
Location after installation: install_root/dbscripts/ProcessChoreographer/
Informix
v On Windows platforms, copy all the SQL and BAT files:
Location on the product media: media_root or extract_directory\dbscripts\
ProcessChoreographer\Informix
Location after installation: install_root\dbscripts\ProcessChoreographer\
Informix
5. Change to the directory where you copied the files.
6. If you want to create a non-production database using default settings that is
suitable for standalone development, evaluation, or demo purposes, enter the
command:
dbaccess - createDatabase.sql

This command creates an Informix database BPEDB for the user ID that you
are using. Make sure that the script output contains no errors. You can use the
dropSchema.sql script to drop only the schema or the SQL command DROP
DATABASE to drop the whole database.
7. If you want to create a database for a production system, you must create your
database manually:
a. Create a database, for example named BPEDB.
b. Create the Dbspaces for your database.
On Windows systems, read the instructions in the createDbspace.bat file.
Adjust the value parameters in the script to values appropriate for your
environment, then run the file.
On UNIX and Linux systems, read the instructions in the createDbspace.sh
file. Adjust the value parameters in the script to values appropriate for your
environment, then run the file.
c. Run the script to create the schema, by entering the command:
dbaccess databaseName createSchema.sql

where databaseName is the name of the database, for example BPEDB.

188

Business Process Choreographer

d. Check the script output for any errors. If you want to drop the schema, use
the dropSchema.sql script.
Results
The database for Business Process Choreographer exists.

Creating a Microsoft SQL Server database for Business


Process Choreographer
Only use this task if you want to create a Microsoft SQL Server database for
Business Process Choreographer before you configure Business Process
Choreographer, or before you have installed the product.
Before you begin
You completed Planning the BPEDB database on page 117.
Procedure
1. Install a Microsoft SQL Server, on the server that hosts the database. Make sure
that the following requirements are met:
v The server must support Unicode.
v The database server must be configured for distributed transactions.
v The instance must be case-sensitive instance. If you already have an SQL
Server that was created with the case-insensitive option, run the rebuild
master tool and change the collation settings to case-sensitive.
For more information about these configuration options, refer to the
documentation for Microsoft SQL Server.
2. Make sure that the database server and the Distributed Transaction Coordinator
(DTC) are running.
3. Copy all the Business Process Choreographer database SQL script files to the
server that hosts the database. The scripts are located in the following
directories:
v On Linux, and UNIX platforms:
Location on the product media: media_root or extract_directory/dbscripts/
ProcessChoreographer/SQLServer
Location after installation: install_root/dbscripts/ProcessChoreographer/
SQLServer
v On Windows platforms:
Location on the product media: media_root or extract_directory\dbscripts\
ProcessChoreographer\SQLServer
Location after installation: install_root\dbscripts\ProcessChoreographer\
SQLServer
4. Change to the directory where you copied the SQL scripts.
5. Perform one of the following:
v If you want to create a non-production SQL Server database, named
BPEDB, for stand-alone development, evaluation, or demonstration
purposes:
a. Run one of the following scripts, as described in the header of the file.
createDatabase.sql
createDatabaseUnicode.sql for a Unicode database
Chapter 4. Configuring Business Process Choreographer

189

For example, enter:


sqlcmd -U userID -P password -i createDatabase.sql

b. Make sure that the script output contains no errors. If errors occur, you
can drop the schema using the dropSchema.sql script.
v If you want to create a production SQL Server database, create your database
manually:
a. Create the database, for example, named BPEDB.
b. To create the schema, customize a copy of one of the following scripts, as
described in the header of the file, using the values you planned, then
run it.
createSchema.sql
createSchemaUnicode.sql if you created a Unicode database
For example, enter:
sqlcmd -U userID -P password -i createSchema.sql

c. Make sure that the script output contains no errors. If errors occur, you
can drop the schema using the dropSchema.sql script.
Results
The database for Business Process Choreographer exists.

Creating an Oracle database for Business Process


Choreographer
Only use this task if you want to create an Oracle database for Business Process
Choreographer before you configure Business Process Choreographer, or before
you have installed the product.
Before you begin
You completed Planning the BPEDB database on page 117.
Procedure
1. Install the Oracle server on the computer that hosts the database. Make sure
that you are using the 32-bit Oracle libraries that are located in the lib32
subdirectory.
2. On Linux and UNIX systems, make sure that the environment variables
ORACLE_BASE and ORACLE_HOME are set for the root user.
3. Check the class path to be sure that your JDBC driver is using the correct JAR
file:
v For Oracle 9i and 10g, use the ojdbc14.jar file.
v For Oracle 11g, use the ojdbc5.jar file.
4. On Linux and UNIX systems, create soft links to the following Oracle libraries
in the /usr/lib directory:
v For Oracle 10g: Link to: libclnt.so.10.1.
v For Oracle 9i: Link to: libnnz10.so, libclnt.so.10.1, libclntsh.so.10.1, and
libocijdbc10.so.
For more detailed information on how to set up the Oracle OCI client, refer to
the documentation provided by Oracle.
5. Create an Oracle database using the Database Configuration Assistant, for
example, with the name BPEDB. There is no script to quickly create a default

190

Business Process Choreographer

Oracle database for Business Process Choreographer. Make sure that you
select the JServer option for the database. The database must be created to
have a Unicode code page.
6. Start the Oracle listener by entering the command:
lsnrctl start

7. Optional: If you do not want to customize the table space and schema, you
can skip the rest of the steps in this task, in which case, the default table space
and schema will be created the first time that Business Process Choreographer
attempts to use the database.
8. Copy all the Business Process Choreographer database SQL script files to the
server that hosts the database. The scripts are located in the following
directories:
v On Linux, and UNIX platforms:
Location on the product media: media_root or extract_directory/dbscripts/
ProcessChoreographer/Oracle
Location after installation:install_root/dbscripts/ProcessChoreographer/
Oracle
v On Windows platforms:
Location on the product media:media_root or extract_directory\dbscripts\
ProcessChoreographer\Oracle
Location after installation:install_root\dbscripts\ProcessChoreographer\
Oracle
9. Change to the directory where you copied the SQL scripts.
10. If you do not want to create the schema in the default instance, set the
ORACLE_SID environment variable to the SID of the database you created in
step 5 on page 190.
11. Make sure that the user who runs these scripts has at least the following
database privileges: CREATE SESSION, CREATE TABLESPACE, DROP
TABLESPACECREATE TABLE, and CREATE VIEW.
12. Customize a copy of the createTablespace.sql table space creation script
according to what you planned in Planning the BPEDB database on page
117 and the instructions in the header of the script file.
13. To create the table spaces, run the createTablespace.sql script. For test
purposes, you can use the same location for all table spaces and pass the path
as a command-line argument to the script, for example, on a Windows system,
using user ID bpeuser, password bpepwd, database name BPEDB, and
table space path d:\mydb\ts, enter:
sqlplus bpeuser/bpepwd@BPEDB @createTablespace.sql d:\mydb\ts

If you want to drop the table spaces, you can use the dropTablespace.sql
script.
14. Make sure that the user who will own the tables is granted sufficient quota on
all the table spaces that were created in the previous step.
15. Edit the schema creation script createSchema.sql according to the instructions
at the top of the file, and replace the placeholder @SCHEMA@ with the name
of the schema. If the @SCHEMA@ is different from the user who runs the
createSchema.sql script, ensure that this user has the following database
privileges: CREATE ANY TABLE, ALTER ANY TABLE, CREATE ANY INDEX, and CREATE
ANY VIEW.
16. To create the schema, run the createSchema.sql script. For example, on
Windows systems, enter:
Chapter 4. Configuring Business Process Choreographer

191

sqlplus bpeuser/bpepwd@BPEDB @createSchema.sql

Results
The database for Business Process Choreographer exists.

Configuring the people directory provider


Use this task to configure the Lightweight Directory Access Protocol (LDAP) or
Virtual Member Manager (VMM) people directory provider that Business Process
Choreographer uses to determine who can start a process or claim an activity or a
task.
About this task
Each type of supported people directory service requires a corresponding people
directory provider. The following people directory providers are supported:
Table 15. Supported people directory providers
People directory provider

People directory provider option

Lightweight Directory Access Protocol


(LDAP) directory

LDAP people directory provider

Virtual Member Manager

VMM people directory provider

Local operating system user registry

System people directory provider

WebSphere Application Server user registry

User Registry people directory provider

All of these plug-ins are already installed with the default configurations. You can
use the user registry and system plug-ins with the default configurations. For
VMM, the default configuration is normally sufficient.

Configuring the Virtual Member Manager people directory


provider
Configure the Virtual Member Manager (VMM) people directory provider for
Business Process Choreographer to perform people assignment, which determines
who can start a process or claim an activity or a task. The default people directory
provider is ready to use, and only needs to be configured if you introduce custom
people assignment criteria.
Before you begin
You have already configured a federated repository.
Procedure
1. Make a copy of the standard transformation file for VMM, and give it a
different name, for example, myVMMTransformation.xsl.
v On Windows platforms, in install_root\ProcessChoreographer\Staff\
VMMTransformation.xsl
v On Linux, UNIX, and i5/OS platforms in install_root/
ProcessChoreographer/Staff/VMMTransformation.xsl
2. Adapt your copy of the transformation file to suit the LDAP schema for your
organization, as described in Adapting the LDAP transformation file on page
195.

192

Business Process Choreographer

Attention: Do not modify the original version of the transformation file


because it can be overwritten without warning in the future when applying a
service or fix pack.
3. If Business Process Choreographer is configured on a cluster, make your copy
of the transformation file available on each WebSphere Process Server
installation that hosts members of the cluster. The transformation file must be
put in the Staff subdirectory of the ProcessChoreographer directory.
4. In the administrative console, click Resources People directory provider.
5. Select the appropriate node.
Option

Description

For a standalone profile:

There is only one node displayed.

In a network deployment environment,


where Business Process Choreographer is
configured on a single server:

Select the node that contains the server.

In a network deployment environment,


where Business Process Choreographer is
configured on a cluster:

You must configure the people directory


provider (perform step 6) on every node that
hosts members of the cluster. Select the first
node, configure the people directory
provider on that node, then repeat the
configuration (step 6) for all other nodes that
host members of the cluster.

6. To
a.
b.
c.

d.
e.
f.
g.

create a new VMM people directory configuration:


Click VMM People Directory Provider.
In the Additional Properties, select People directory configuration.
Click New Browse, and select your copy of the Extensible Stylesheet
Language (XSL) transformation file that you adapted in step 2 on page 192.
If the node agent is running, you can browse the file system of remote
nodes to select the transformation file, any file that you select will be copied
to the local ProcessChoreographer directorys Staff subdirectory.
Click Next. The file will be copied to the selected node.
In the General Properties section, enter an administrative name for the new
people directory configuration.
Optional: Enter a description.
Enter a unique Java Naming and Directory Interface (JNDI) name that will
identify this configuration to the system. For example, bpe/staff/
myvmmconfiguration

Note: There are no other configuration parameters


h. Click OK, then click Save.
7. To activate the provider configuration, stop and start the server or servers
where you configured the provider.
8. If you have problems with any of these steps, refer to the Troubleshooting
WebSphere Process Server PDF.
Results
The VMM people directory provider is configured.

Chapter 4. Configuring Business Process Choreographer

193

Configuring the LDAP people directory provider


Use this task to configure the Lightweight Directory Access Protocol (LDAP)
people directory provider for Business Process Choreographer to perform people
assignment, which determines who can start a process or claim an activity or a
task.
Before you begin
You have performed the planning for LDAP described in Planning for the people
directory provider on page 130.
About this task
The LDAP people directory provider configuration is initialized with a URL that
points to a local LDAP server. You must change the URL later, to point to the real
LDAP server, which is normally remote to the application server. The LDAP people
directory provider is configured for an LDAP server that allows anonymous access.
Procedure
1. Make a copy of the standard transformation file for LDAP, and give it a
different name, for example, myLDAPTransformation.xsl.

2.

3.

4.
5.

v On Windows platforms, it is in install_root\ProcessChoreographer\Staff\


LDAPTransformation.xsl
v On Linux, UNIX, and i5/OS platforms it is in install_root/
ProcessChoreographer/Staff/LDAPTransformation.xsl
Adapt your copy of the transformation file to suit the LDAP schema for your
organization, as described in Adapting the LDAP transformation file on page
195.
Attention: Do not modify the original version of the transformation file
because it can be overwritten without warning in the future when applying a
service or fix pack.
If Business Process Choreographer is configured on a cluster, make your copy
of the transformation file available on each WebSphere Process Server
installation that hosts members of the cluster. The transformation file must be
put in the Staff subdirectory of the ProcessChoreographer directory.
In the administrative console, click Resources People directory provider.
Select the appropriate node.

Option

Description

For a standalone profile:

There is only one node displayed.

In a network deployment environment,


where Business Process Choreographer is
configured on a single server:

Select the node that contains the server.

In a network deployment environment,


where Business Process Choreographer is
configured on a cluster:

You must configure the people directory


provider (perform step 6) on every node that
hosts members of the cluster. Select the first
node, configure the people directory
provider on that node, then repeat the
configuration (step 6) for all other nodes that
host members of the cluster.

6. To create a new LDAP configuration on the selected node:


a. Click LDAP People Directory Provider.

194

Business Process Choreographer

b. Under Additional Properties, click People directory configuration.


c. Click New Browse, and select your copy of the Extensible Stylesheet
Language (XSL) transformation file that you adapted in step 2 on page 194.
If the node agent is running, you can browse the file system of remote
nodes to select the transformation file, any file that you select will be copied
to the local ProcessChoreographer directorys Staff subdirectory.
d. Click Next. The file will be copied to the selected node.
e. Enter an administrative name for the people directory configuration.
f. Enter a description.
g. Enter the Java Naming and Directory Interface (JNDI) name for human
tasks to use to reference this provider. For example, bpe/staff/ldapserver1
h. Click Apply.
i. Click Custom Properties.
j. For each of the required properties and for any optional properties that you
planned in 2 on page 130, click the name of the property, enter a value, and
click OK.
Note: For the optional additional properties, you can set properties that are
defined for JNDI, for example to enable LDAP referrals. For providerURL,
you can specify a URL starting with ldap:// or ldaps://.
k. To apply the changes, click Save.
7. To activate the provider configuration, stop and start the server or servers
where you configured the provider.
8. If you have problems with any of these steps, refer to the Troubleshooting
WebSphere Process Server PDF.
Results
Human tasks and processes can now use the people assignment services to resolve
people assignment queries, and to determine which activities can be performed by
which people.

Adapting the LDAP transformation file


Describes how to adapt the LDAP transformation XSL file to suit your
organizations LDAP schema.
The default LDAPTransformation.xsl file maps predefined people assignment
criteria to LDAP queries, which make use of elements of the default LDAP schema
assumed by WebSphere. This schema assumes the following:
v
v
v
v
v
v

The LDAP object class for group entries is groupOfName.


The group entry attribute containing the member DNs for the group is member.
The LDAP object class for person entries is inetOrgPerson.
The attribute containing the login ID in a person entry is uid.
The person entry attribute containing the e-mail address of a person is mail.
The person entry attribute containing the distinguished name of the manager of
a person is manager.

If your LDAP schema uses different object class and attribute names, you must
change these settings in the LDAP transformation files that you use. Make a copy
of the original LDAPTransformation.xsl file, as described in Configuring the
LDAP people directory provider on page 194.

Chapter 4. Configuring Business Process Choreographer

195

Attention: Do not make modifications to the original version of the


transformation file because it might be overwritten without warning in the future
when applying a service pack or fix pack.
It is normally sufficient to change the settings for all people assignment criteria by
editing the variable declaration part of the file:
<xsl:variable name="DefaultGroupClass">groupOfNames</xsl:variable>
<xsl:variable name="DefaultGroupClassMemberAttribute">member</xsl:variable>
<xsl:variable
<xsl:variable
<xsl:variable
<xsl:variable

name="DefaultPersonClass">inetOrgPerson</xsl:variable>
name="DefaultUserIDAttribute">uid</xsl:variable>
name="DefaultMailAttribute">mail</xsl:variable>
name="DefaultManagerAttribute">manager</xsl:variable>

You can apply changes within the XSL templates that transform the individual staff
assignment criteria, as illustrated in the following examples.

Example: GroupMembers
Changing the object class for group entries to groupOfUniqueNames, the group
entry attribute containing the member DN list to uniqueMember, and the person
entry attribute containing the login in to cn:
<sldap:usersOfGroup>
...
<sldap:attribute>
<xsl:attribute name="name">uniqueMember</xsl:attribute>
<xsl:attribute name="objectclass">groupOfUniqueNames</xsl:attribute>
<xsl:attribute name="usage">recursive</xsl:attribute>
</sldap:attribute>
...
<sldap:attribute>
<xsl:attribute name="name">cn</xsl:attribute>
<xsl:attribute name="objectclass">inetOrgPerson</xsl:attribute>
<xsl:attribute name="usage">simple</xsl:attribute>
</sldap:attribute>
...
<sldap:resultObject>
<xsl:attribute name="objectclass">groupOfUniqueNames</xsl:attribute>
<xsl:attribute name="usage">recursive</xsl:attribute>
<sldap:resultAttribute>
<xsl:attribute name="name">uniqueMember</xsl:attribute>
<xsl:attribute name="destination">intermediate</xsl:attribute>
</sldap:resultAttribute>
</sldap:resultObject>
<sldap:resultObject>
<xsl:attribute name="objectclass"><xsl:value-of select="$DefaultPersonClass"/></xsl:attribute>
<xsl:attribute name="usage">simple</xsl:attribute>
<sldap:resultAttribute>
<xsl:attribute name="name">cn</xsl:attribute>
<xsl:attribute name="destination">userID</xsl:attribute>
</sldap:resultAttribute>
<sldap:resultAttribute>
<xsl:attribute name="name"><xsl:value-of select="$DefaultMailAttribute"/></xsl:attribute>
<xsl:attribute name="destination">eMailAddress</xsl:attribute>
</sldap:resultAttribute>
<sldap:resultAttribute>
<xsl:attribute name="name"><xsl:value-of select="$DefaultLocaleAttribute"/></xsl:attribute>
<xsl:attribute name="destination">preferredLocale</xsl:attribute>
</sldap:resultAttribute>
</sldap:resultObject>
</sldap:usersOfGroup>

Example: GroupMembersWithoutFilteredUsers
Changing the LDAP filter operator to >=.

196

Business Process Choreographer

<sldap:StaffQueries>
<sldap:usersOfGroup>
...
</sldap:usersOfGroup>
<sldap:intermediateResult>
<xsl:attribute name="name">filteredusers</xsl:attribute>
<sldap:search>
<xsl:attribute name="filter">
<xsl:value-of select="staff:parameter[@id=FilterAttribute]"/>
>=
<xsl:value-of select="staff:parameter[@id=FilterValue]"/>
</xsl:attribute>
...
<sldap:search>
...
</sldap:intermediateResult>
...
</sldap:StaffQueries>

Example: GroupSearch
Changing the search attribute to MyType, the object class to mypersonclass, and
the attribute containing the login ID to myuid.
<sldap:StaffQueries>
...
<sldap:search>
<xsl:attribute name="filter">
(&
...
<xsl:if test="staff:parameter[@id=MyType]!="">
(<xsl:value-of select="$GS_Type"/>=
<xsl:value-of select=staff:parameter[@id=Type]"/>)
</xsl:if>
)
...
</xsl:attribute>
<sldap:attribute>
<xsl:attribute name="name">myuid</xsl:attribute>
<xsl:attribute name="objectclass">mypersonclass</xsl:attribute>
<xsl:attribute name="usage">simple</xsl:attribute>
</sldap:attribute>
...
<sldap:resultObject>
<xsl:attribute name="objectclass">mypersonclass</xsl:attribute>
<xsl:attribute name="usage">simple</xsl:attribute>
<sldap:resultAttribute>
<xsl:attribute name="name">myuid</xsl:attribute>
<xsl:attribute name="destination">userID</xsl:attribute>
</sldap:resultAttribute>
<sldap:resultAttribute>
<xsl:attribute name="name"><xsl:value-of select="$DefaultMailAttribute"/></xsl:attribute>
<xsl:attribute name="destination">eMailAddress</xsl:attribute>
</sldap:resultAttribute>
<sldap:resultAttribute>
<xsl:attribute name="name"><xsl:value-of select="$DefaultLocaleAttribute"/></xsl:attribute>
<xsl:attribute name="destination">preferredLocale</xsl:attribute>
</sldap:resultAttribute>
</sldap:resultObject>
<sldap:search>
</sldap:StaffQueries>

Example: Manager of Employee


Changing the attribute containing the manager DN to managerentry and the
source of the manager login ID attribute to name.
<sldap:StaffQueries>
<sldap:intermediateResult>
...
<sldap:user>

Chapter 4. Configuring Business Process Choreographer

197

...
<xsl:attribute name="name">managerentry</xsl:attribute>
...
<sldap:resultObject>
<xsl:attribute name="objectclass"><xsl:value-of select="$DefaultPersonClass"/></xsl:attribute>
<xsl:attribute name="usage">simple</xsl:attribute>
<sldap:resultAttribute>
<xsl:attribute name="name">managerentry</xsl:attribute>
<xsl:attribute name="destination">intermediate</xsl:attribute>
</sldap:resultAttribute>
</sldap:resultObject>
</sldap:user>
</sldap:intermediateResult>
<sldap:user>
...
<xsl:attribute name="name">name</xsl:attribute>
...
<sldap:resultObject>
<xsl:attribute name="objectclass"><xsl:value-of select="$DefaultPersonClass"/></xsl:attribute>
<xsl:attribute name="usage">simple</xsl:attribute>
<sldap:resultAttribute>
<xsl:attribute name="name">name</xsl:attribute>
<xsl:attribute name="destination">userID</xsl:attribute>
</sldap:resultAttribute>
<sldap:resultAttribute>
<xsl:attribute name="name"><xsl:value-of select="$DefaultMailAttribute"/></xsl:attribute>
<xsl:attribute name="destination">eMailAddress</xsl:attribute>
</sldap:resultAttribute>
<sldap:resultAttribute>
<xsl:attribute name="name"><xsl:value-of select="$DefaultLocaleAttribute"/></xsl:attribute>
<xsl:attribute name="destination">preferredLocale</xsl:attribute>
</sldap:resultAttribute>
</sldap:resultObject>
</sldap:user>
</sldap:StaffQueries>

Example: PersonSearch
Changing the search attribute to MyAttribute, the object class to mypersonclass,
and the source of the return attribute to myuid.
<sldap:StaffQueries>
...
<sldap:search>
<xsl:attribute name="filter">
(&
...
<xsl:if test="staff:parameter[@id=MyAttribute]!="">
(<xsl:value-of select="$PS_UserID"/>=
<xsl:value-of select=staff:parameter[@id=UserID]"/>)
)
</xsl:if>
...
</xsl:attribute>
<sldap:attribute>
<xsl:attribute name="name">myuid</xsl:attribute>
<xsl:attribute name="objectclass">mypersonclass</xsl:attribute>
<xsl:attribute name="usage">simple</xsl:attribute>
</sldap:attribute>
...
<sldap:resultObject>
<xsl:attribute name="objectclass">mypersonclass</xsl:attribute>
<xsl:attribute name="usage">simple</xsl:attribute>
<sldap:resultAttribute>
<xsl:attribute name="name">myuid</xsl:attribute>
<xsl:attribute name="destination">userID</xsl:attribute>
</sldap:resultAttribute>
<sldap:resultAttribute>
<xsl:attribute name="name"><xsl:value-of select="$DefaultMailAttribute"/></xsl:attribute>
<xsl:attribute name="destination">eMailAddress</xsl:attribute>
</sldap:resultAttribute>
<sldap:resultAttribute>

198

Business Process Choreographer

<xsl:attribute name="name"><xsl:value-of select="$DefaultLocaleAttribute"/></xsl:attribute>


<xsl:attribute name="destination">preferredLocale</xsl:attribute>
</sldap:resultAttribute>
</sldap:resultObject>
</sldap:search>
</sldap:StaffQueries>

Example: Users
Changing the source of the return attribute to myuid and the object class to
mypersonclass.
<sldap:user>
...
<xsl:attribute name="attribute">myuid</xsl:attribute>
<xsl:attribute name="objectclass">mypersonclass</xsl:attribute>
<sldap:resultObject>
<xsl:attribute name="objectclass">mypersonclass</xsl:attribute>
<xsl:attribute name="usage">simple</xsl:attribute>
<sldap:resultAttribute>
<xsl:attribute name="name">myuid</xsl:attribute>
<xsl:attribute name="destination">userID</xsl:attribute>
</sldap:resultAttribute>
<sldap:resultAttribute>
<xsl:attribute name="name"><xsl:value-of select="$DefaultMailAttribute"/></xsl:attribute>
<xsl:attribute name="destination">eMailAddress</xsl:attribute>
</sldap:resultAttribute>
<sldap:resultAttribute>
<xsl:attribute name="name"><xsl:value-of select="$DefaultLocaleAttribute"/></xsl:attribute>
<xsl:attribute name="destination">preferredLocale</xsl:attribute>
</sldap:resultAttribute>
</sldap:resultObject>
</sldap:user>

Configuring people substitution


This topic describes how to configure people substitution for Business Process
Choreographer.
Before you begin
You have configured WebSphere security for Federated Repositories, and if you
introduce custom people assignment criteria, you have also performed
Configuring the Virtual Member Manager people directory provider on page
192. You know whether you will use a file registry, property extension registry, or
an existing LDAP schema to store the property extensions.
About this task
To use people substitution in a production environment, you must use the Virtual
Member Manager (VMM) property extension repository as described in this topic.
If however, you only want to use people substitution in a single-server test
environment, you can use the file registry that is associated by default with
federated repositories, without having to configure VMM.
Procedure
1. Add the two attributes, isAbsent as a single-valued string, and substitutes
as a multi-valued string, to the VMM definition for PersonAccount:
a. Locate the wimxmlextension.xml file:
v On Linux, UNIX, and i5/OS platforms, it is located in
profile_root/config/cells/cell_name/wim/model
Chapter 4. Configuring Business Process Choreographer

199

v On Windows platforms, it is located in profile_root\config\cells\


cell_name\wim\model
b. Make a backup copy of the wimxmlextension.xml file.
c. Edit the original copy of the wimxmlextension.xml file, and make sure that
it contains the following definitions, which add the two attributes that are
needed for user substitution to the PersonAccount entity type:
<wim:propertySchema nsURI="http://www.ibm.com/websphere/wim"
dataType="STRING" multiValued="false" propertyName="isAbsent">
<wim:applicableEntityTypeNames>PersonAccount
</wim:applicableEntityTypeNames>
</wim:propertySchema>
<wim:propertySchema nsURI="http://www.ibm.com/websphere/wim"
dataType="STRING" multiValued="true" propertyName="substitutes">
<wim:applicableEntityTypeNames>PersonAccount
</wim:applicableEntityTypeNames>
</wim:propertySchema>

If you are using a file registry, fileRegistry.xml, skip to step 4 on page 202.
2. Set up the property extension repository. For more information about setting up
a property extension repository, see Configuring a property extension
repository in a federated repository configuration.
a. Make sure that a database is available to store the property extensions.
b. Make sure that the JDBC driver class is available on the server classpath.
Click Environments WebSphere Variable to check. If necessary, add the
JDBC driver to the classpath by clicking Application servers server_name
Process Definition Java Virtual Machine Configuration. For DB2,
add db2jcc.jar,db2jcc_license_cu.jar and db2jcc_license_cisuz.jar to the
servers classpath, and click Apply Save
c. Configure a DB2 Universal JDBC driver provider and type-4 data source for
VMM using the administrative console. Set the
webSphereDefaultIsolationLevel custom property for the data source to the
value 2. For more information about changing the default isolation level, see
Changing the default isolation level for non-CMP applications and
describing how to do so using a new custom property
webSphereDefaultIsolationLevel.
d. Restart the server.
e. Make a backup copy of the wimlaproperties.xml file.
v On Linux, UNIX, and i5/OS platforms, it is located in
profile_root/config/cells/cell_name/wim/model
v On Windows platforms, it is located in profile_root\config\cells\
cell_name\wim\model
f. Edit the original copy of the wimlaproperties.xml file, and add the following
definitions:
<wimprop:property wimPropertyName="isAbsent" dataType="String"
valueLength="128" multiValued="false">
<wimprop:applicableEntityName>
<wimprop:entityName>PersonAccount</wimprop:entityName>
</wimprop:applicableEntityName>
</wimprop:property>
<wimprop:property wimPropertyName="substitutes" dataType="String"
valueLength="128" multiValued="true">
<wimprop:applicableEntityName>
<wimprop:entityName>PersonAccount</wimprop:entityName>
</wimprop:applicableEntityName>
</wimprop:property>

g. Make sure that the application server (or in a network deployment


environment, the deployment manager) is running. Be aware not to use the
-conntype NONE option for the wsadmin utility.

200

Business Process Choreographer

h. Use the VMM administrative task


setupIdMgrPropertyExtensionRepositoryTables to create the substitution
properties in the Property Extension Repository database. For more details,
see Setting up an entry mapping repository, a property extension repository,
or a custom registry database repository using wsadmin commands. For
example, using a DB2 database on a Windows platform:
$AdminTask setupIdMgrPropertyExtensionRepositoryTables {
-reportSqlError true
-schemaLocation install_root\etc\wim\setup
-laPropXML install_root\etc\wim\setup\wimlaproperties.xml
-databaseType db2
-dbURL jdbc:db2:
-dbDriver com.ibm.db2.jcc.DB2Driver
-dbAdminId userID
-dbAdminPassword password }

i. If you are using a Lightweight Directory Access Protocol (LDAP) user


repository, locate the wimconfig.xml file.
v On Linux, UNIX, and i5/OS platforms the path is profile_root/config/
cells/cellName/wim/config/wimconfig.xml
v On Windows platforms, the path is profile_root\config\cells\cellName\
wim\config\wimconfig.xml
Edit the file and add the following entries to exclude the substitution
attributes from the LDAP repository:
<config:repositories xsi:type="config:LdapRepositoryType"
adapterClassName="com.ibm.ws.wim.adapter.ldap.LdapAdapter"
id="ldaprepo1" ...>
...
<config:attributeConfiguration>
<config:propertiesNotSupported name="isAbsent"/>
<config:propertiesNotSupported name="substitutes"/>
</config:attributeConfiguration>

j. Activate the extension property repository:


1) Using the setIdMgrPropertyExtensionRepository command. For more
details, see Setting up an entry mapping repository, a property extension
repository, or a custom registry database repository using wsadmin
commands. For example, using a DB2 database named VMMDB, a data
source named VMMDS:
$AdminTask setIdMgrPropertyExtensionRepository {
-dataSourceName jdbc/VMMDS
-databaseType db2
-dbURL jdbc:db2:VMMDB
-dbAdminId userID
-dbAdminPassword password
-JDBCDriverClass com.ibm.db2.jcc.DB2Driver
-entityRetrievalLimit 10 }

2) Verify that the wimconfig.xml file contains an entry similar to the


following:
<config:propertyExtensionRepository
adapterClassName="com.ibm.ws.wim.lookaside.LookasideAdapter"
id="LA"
databaseType="db2"
dataSourceName="jdbc/VMMDS"
dbAdminId="userID"
dbAdminPassword="{xor}PasswordXOR"
dbURL="jdbc:db2:VMMDB"
entityRetrievalLimit="10"
JDBCDriverClass="com.ibm.db2.jcc.DB2Driver"/>>

3. If you use an LDAP schema to hold the substitution information: It may or


may not already have definitions for isAbsent and substitutes (possibly
with different names). Whether you have existing definitions, or you will create
new ones, make sure of the following:
a. The LDAP directory must allow write operations.
b. The attribute for absence information (isAbsent) must be of type Boolean
or a String.
Chapter 4. Configuring Business Process Choreographer

201

c. The attribute that defines who the person can substitute for (substitutes)
must be of type String, multi-valued, and permit a length up to 128
characters.
d. If your existing or chosen attribute names are not isAbsent and
substitutes, you must define your attribute names in the administrative
console by clicking Servers Application servers server_name or Servers
Clusters cluster_name, then under Business Integration, expand
Business Process Choreographer, and click Human Task Manager
Configuration Custom properties, then set the desired names for the
custom properties Substitution.SubstitutesAttribute and
Substitution.AbsenceAttribute.
4. Restart the server.
5. Enable substitution in the Human Task Manager:
a. Using the administrative console, click Servers Application servers
server_name or Servers Clusters cluster_name, then under Business
Integration, expand Business Process Choreographer, and click Human
Task Manager, then either Runtime or Configuration.
b. To enable substitution, select Enable substitution.
c. If non-administrators are allowed to perform substitution for other users,
clear the Restrict substitute management to administrators option.
Note: This settings does not affect the ability of users to change substitution
for themselves.
d. Click Apply.
e. If you selected Configuration in step 5a, restart the server to activate the
substitution settings.
6. If you have problems with any of these steps, refer to the Troubleshooting
WebSphere Process Server PDF.
Results
The people assignment service is configured to support user substitution for absent
users.

Configuring Business Process Choreographer Explorer


You can either run a script or use the administrative console to configure Business
Process Choreographer Explorer.
Before you begin
You have configured Business Process Choreographer.
About this task
One or more of the following applies:
v You have not yet installed Business Process Choreographer Explorer.
v You want to manage an existing Business Process Choreographer configuration.
v You want to add another instance of Business Process Choreographer Explorer to
an already managed Business Process Choreographer configuration.
To configure Business Process Choreographer Explorer, perform the following:

202

Business Process Choreographer

Procedure
1. If you want to use a script, perform Using the clientconfig.jacl script file to
configure the Business Process Choreographer Explorer on page 204.
2. If you want to use the administrative console, perform Using the
administrative console to configure the Business Process Choreographer
Explorer.
3. Make sure that the BPCExplorer Web module has environment entries for the
URL for the Business Flow Manager and Human Task Manager
Representational State Transfer (REST) APIs which match the context root you
set for the REST APIs. In the administrative console, click Applications
Enterprise Applications BPCExplorer_node_server or BPCExplorer_cluster
Environment entries for Web modules. For the Web module BPCExplorer,
make sure that the values for the environment entries named bfmRESTAPIURL
and htmRESTAPIURL are full URLs, which match the context roots you set for
the Business Process Choreographer REST APIs. For example, if the context
root for the Business Flow Manager REST API is /rest/bpm/bfm then the full
URL might be something like http://localhost:9080/rest/bpm/bfm.
Results
Business Process Choreographer Explorer is configured and ready to use.
What to do next
Start Business Process Choreographer Explorer.

Using the administrative console to configure the Business


Process Choreographer Explorer
You can use the administrative console to configure Business Process
Choreographer Explorer.
Procedure
1. Click Servers Application servers server_name or Servers Clusters
cluster_name, then under Business Integration, expand Business Process
Choreographer, and click Business Process Choreographer Explorer.
2. To create a new explorer configuration, click Add.
3. Enter values for the following fields:
v The Context root must be unique on the deployment target server or cluster.
v Explorer search result limit.
v Managed Business Process Choreographer container
4. Click Apply. Messages are displayed indicating the progress.
5. Optional: If any problems are reported, check the SystemOut.log file.
6. Start the enterprise application named BPCExplorer_scope. Where scope
identifies the server or cluster where you configure the Business Process
Choreographer Explorer.
Results
Business Process Choreographer Explorer is configured and ready to use.
What to do next

Chapter 4. Configuring Business Process Choreographer

203

Start Business Process Choreographer Explorer.

Using the clientconfig.jacl script file to configure the Business


Process Choreographer Explorer
This script file configures Business Process Choreographer Explorer and all the
necessary resources on a server or cluster.

Purpose
This script file configures Business Process Choreographer Explorer. This script file
can either be run interactively, or in batch mode.

Location
The clientconfig.jacl script file is located in the Business Process Choreographer
config directory:
v On Linux, UNIX, and i5/OS platforms: In the directory install_root/
ProcessChoreographer/config
v On Windows platforms: In the directory install_root\ProcessChoreographer\
config

Running the script in a stand-alone server environment


Any parameters for the wsadmin command must be provided on the command
line, if they are not specified, they will not be prompted for. In a stand-alone server
environment:
v Include the -conntype NONE option only if the application server is not running.
v If the server is running and WebSphere administrative security is enabled,
include the -user and -password options.
v If you are not configuring the default profile, add the -profileName option.

Running the script in a network deployment environment


Any parameters for the wsadmin command must be provided on the command
line, if they are not specified, they will not be prompted for. In a network
deployment environment:
v Run the script on the deployment manager node.
v Include the -conntype NONE option only if the deployment manager is not
running.
v If WebSphere administrative security is enabled, include the -user and
-password options.
v If you are not configuring the default profile, add the -profileName option.

Configuring the Business Process Choreographer Explorer


non-interactively
Change your current directory to install_root in the config fs and perform the
following:
On Linux and UNIX platforms, enter the command:
bin/wsadmin.sh -f ProcessChoreographer/config/clientconfig.jacl options

On i5/OS, enter the command:

204

Business Process Choreographer

bin/wsadmin -f ProcessChoreographer/config/clientconfig.jacl options

On Windows platforms, enter the command:


bin\wsadmin.bat -f ProcessChoreographer/config/clientconfig.jacl options

Where options are:


( [-user userName][-password password] | [-conntype NONE] )
[-profileName profileName]
( [-node nodeName][-server serverName] )
[-cluster clusterName]
[-contextRootExplorer explorerContextRoot]
[-hostName explorerVirtualHostname]
[-precompileJSPs { yes | no }]
( ( [-remoteNode nodeName][-remoteServer serverName] )
| [-remoteCluster clusterName] )
[-maxListEntries maximum]
[-explorerHost explorerURL]
-restAPIBFM restAPIURL
-restAPIHTM restAPIURL

Note: If you provide all the necessary parameters on the command line, you will
not be prompted for them. Any required parameters that are not specified on the
command line are prompted for interactively in the sequence that they are listed.

Parameters
You can use the following parameters when invoking the script using wsadmin:
-cluster clusterName
Where clusterName is the name of the cluster where Business Process
Choreographer Explorer will be configured. This parameter is optional. Do not
specify this option in a standalone server environment, nor if you specify the
node and server.
-contextRootExplorer contextRootExplorer
Where contextRootExplorer is the context root for the Business Process
Choreographer Explorer. The context root must be unique within the
WebSphere cell. The default value is /bpc.
-explorerHost explorerURL
Where explorerURL is the URL of the Business Process Choreographer Explorer.
The value of this parameter is used to link the Human Task Manager of the
managed Business Process Choreographer configuration to this particular
Business Process Choreographer Explorer instance. This parameter defaults to
an empty string, which means that the link will not be made. You can make or
change the link later using the administrative console.
-hostName VirtualHostname
Where VirtualHostname is the virtual host where the Business Process
Choreographer Explorer, the Web service bindings of the Business Flow
Manager and Human Task Manager APIs, and the REST bindings of the
Business Flow Manager and Human Task Manager APIs will run. The default
value is default_host.
-maxListEntries maximum
Where maximum is the maximum number of results that the Business Process
Choreographer Explorer will return for a query. The default is 10000.

Chapter 4. Configuring Business Process Choreographer

205

-node nodeName
Where nodeName is the name of the node where Business Process
Choreographer Explorer will be configured. If you do not specify this
parameter, the default is the local node.
-precompileJSPs { no | yes }
Determines whether Java Server Pages (JSPs) will be precompiled, or not. The
default is no. Note that it is not possible to debug precompiled JSPs.
-remoteCluster clusterName
Use this parameter, if you do not want to connect to the local Business Process
Choreographer configuration and you do not specify remoteNode and
remoteServer. If this parameter is not specified, it defaults to the value of the
-cluster parameter.
-remoteNode nodeName
Use this parameter and remoteServer if you do not want to connect to the local
Business Process Choreographer configuration. If this parameter is not
specified, it defaults to the value of the -node parameter.
-remoteServer serverName
Use this parameter and remoteNode if you do not want to connect to the local
Business Process Choreographer configuration. If this parameter is not
specified, it defaults to the value of the -server parameter.
-restAPIBFM restAPIURL
Where restAPIURLis the URL for the Business Flow Manager REST API, which
is needed to support the graphical process widget for the Business Process
Choreographer Explorer. On a standalone server, the default is computed, for
example, http://localhost:9080/rest/bpm/bfm. In a network deployment
environment there is no default value.
-restAPIHTM restAPIURL
Where restAPIURL is the URL for the Human Task Manager REST API, which
is needed to support the graphical process widget for the Business Process
Choreographer Explorer. On a standalone server, the default is computed, for
example, http://localhost:9080/rest/bpm/htm. In a network deployment
environment there is no default value.
-server serverName
Where serverName is the name of the server where Business Process
Choreographer Explorer will be configured. If you have only one node and
exactly one server, this parameter is optional.

Log files
If you have problems creating the configuration using the clientconfig.jacl script
file, check the following log files:
v clientconfig.log
v wsadmin.traceout
Both files can be found in the logs directory for your profile:
v On Linux, UNIX, and i5/OS platforms: In the directory profile_root/logs
v On Windows platforms: In the directory profile_root\logs
If you run the script in connected mode, also check the files SystemOut.log and
SystemErr.log that can be found in the subdirectory of the logs directory that is
named after the application server or deployment manager that the wsadmin
scripting client connected to.

206

Business Process Choreographer

Configuring the Business Process Choreographer Observer


Using the Business Process Choreographer Observer is optional, however, before
you can use it, you must setup the database and install the applications.
Before you begin
You have performed Planning for the Business Process Choreographer Observer
on page 132.
About this task
You want to configure the Business Process Choreographer Observer, with its own
database.
Procedure
1. If the database for the Business Process Choreographer does not already exist,
perform Preparing a database for the Business Process Choreographer
Observer on page 208.
2. Perform Configuring the Business Process Choreographer event collector
application on page 245.
3. Perform Configuring the Business Process Choreographer Observer
application on page 249.
4. Perform Changing configuration parameters for the Business Process
Choreographer Observer on page 253.
5. Perform Enabling logging for Business Process Choreographer on page 251.
6. Perform Verifying the Business Process Choreographer Observer on page 262.
Results
The Business Process Choreographer Observer is configured and working.
You can use Business Process Choreographer Observer to generate reports, as
described in Reporting on business processes and activities on page 361.

Removing the Business Process Choreographer Observer


Version 6.0.1 sample
Describes how to remove the Business Process Choreographer Observer sample
provided with Version 6.0.1.
About this task
If you migrated from WebSphere Process Server Version 6.0.1, and used the
Business Process Choreographer Observer sample, you must remove the sample
before you configure the latest version of the Business Process Choreographer
Observer. The applications themselves are not migrated, but the database views
and indexes must be dropped. The data that was collected by the sample is not
migrated, and cannot be used.
Procedure
Drop the database views and indexes that are used by the Business Process
Choreographer Observer and event collector.
Chapter 4. Configuring Business Process Choreographer

207

1. If you use a DB2 database:


a. Connect to the database where the observer schema is located.
b. Locate and run the script to drop the observer sample DB2 schema:
v On Windows platforms: install_root\ProcessChoreographer\sample\
observer\dropObserverSampleSchema_DB2.sql.
v On Linux and UNIX platforms: install_root/ProcessChoreographer/
sample/observer/dropObserverSampleSchema_DB2.sql.
For example, enter:
db2 -tf dropObserverSampleSchema_DB2.sql

2. If you used a Cloudscape database, perform the following in a command


window:
a. Add the derby.jar and derbytools.jar files to your CLASSPATH.
v On Windows platforms: They are located in install_root\derby\bin\
embedded.
v On Linux and UNIX platforms: They are located in install_root/derby/
bin/embedded.
b. Locate and run the script to drop the observer sample Cloudscape schema
as described in the comments in the file:
v On Windows platforms: install_root\ProcessChoreographer\sample\
observer\dropObserverSampleSchema_Cloudscape.sql.
v On Linux and UNIX platforms: install_root/ProcessChoreographer/
sample/observer/dropObserverSampleSchema_Cloudscape.sql.
For example, enter the command:
java -Dij.protocol=jdbc:derby:
-Dij.database=OBSVRDB
org.apache.derby.tools.ij
dropObserverSampleSchema_Cloudscape.sql

Results
The Business Process Choreographer Observer sample has been removed.

Preparing a database for the Business Process


Choreographer Observer
Perform the actions for your database.

Using SQL scripts to create the database for Business Process


Choreographer Observer
You might choose to create the database for the Business Process Choreographer
Observer manually before you configure Business Process Choreographer, or even
before you have installed the product.
Before you begin
You have performed Planning the OBSRVRDB database on page 123.
About this task
Your organization might require that databases be created by a separate database
administrator. If you use the administrative console or the bpeconfig.jacl script to
configure Business Process Choreographer, customized SQL scripts are generated
that you can give to your DBA to create the BPEDB database. However, if you

208

Business Process Choreographer

want to create the database before configuring Business Process Choreographer, or


even before product installation, your DBA must use the non-customized SQL
scripts. This topic describes how to use the non-customized SQL scripts, which are
available on the product media.
Procedure
On the server that hosts the database, create the database according to the
description for your database system.
v Using an SQL script to prepare a DB2 for iSeries database for the Business
Process Choreographer Observer on page 215.
v Using SQL scripts to prepare a DB2 Universal database for the Business Process
Choreographer Observer.
v Using an SQL script to prepare a Derby database for the Business Process
Choreographer Observer on page 229.
v Using SQL scripts to prepare an Oracle database for the Business Process
Choreographer Observer on page 234.
Results
The Business Process Choreographer database exists and is accessible from any
remote servers or cluster members where Business Process Choreographer is
configured.

Preparing a DB2 Universal database for the Business Process


Choreographer Observer
You can either use scripts or an interactive tool to prepare the database.
Using SQL scripts to prepare a DB2 Universal database for the Business Process
Choreographer Observer:
This describes how to use scripts to prepare a DB2 Universal database on Linux,
UNIX, and Windows platforms.
About this task
Your database must already exist. You can either use an existing database, or use a
new one. To perform this task, you must have administration rights for the
destination database.
Procedure
1. If you configured Business Process Choreographer using the bpeconfig.jacl
script in batch mode or using the administrative console, use the generated
SQL script to create the Business Process Choreographer Observer database.
a. Locate the generated createSchema_Observer.sql SQL script.
v If you configured Business Process Choreographer in a network
deployment environment using the administrative console or by running
the bpeconfig.jacl script in connected mode, the
createSchema_Observer.sql script file is generated on the node of the
dmgr.
v If you configured Business Process Choreographer on a standalone server
using the administrative console or by running the bpeconfig.jacl script in
connected mode, the createSchema_Observer.sql script file is generated on
the node where you invoked wsadmin.
Chapter 4. Configuring Business Process Choreographer

209

v If you configured Business Process Choreographer by running the


bpeconfig.jacl script in disconnected mode, the createSchema_Observer.sql
script file is generated on the node of the standalone server.
v On Linux and UNIX platforms:
If you specified a schema qualifier, the generated script is:
profile_root/dbscripts/ProcessChoreographer/DB2/database_name/
database_schema/createSchema_Observer.sql.
If you did not specify a schema qualifier, the generated script is:
profile_root/dbscripts/ProcessChoreographer/DB2/database_name/
createSchema_Observer.sql.
v For Windows platforms:
If you specified a schema qualifier, the generated script is:
profile_root\dbscripts\ProcessChoreographer\DB2\database_name\
database_schema\createSchema_Observer.sql
If you did not specify a schema qualifier, the generated script is:
profile_root\dbscripts\ProcessChoreographer\DB2\database_name\
createSchema_Observer.sql
Where:
database_name
is the name of your database.
database_schema
is the name of the schema, if you are using one.
b. If the database is remote, copy the generated script to the database host. If
you are not authorized to perform this, give your database administrator a
copy of the script and discuss your requirements with her.
c. Optional: You or your database administrator can customize the SQL script.
For example, to specify the allocation of disks and table spaces that you
planned in Planning the OBSRVRDB database on page 123.
d. Run the SQL script on the database host by entering the following
command:
db2 -tf createSchema_Observer.sql

2. If you configured Business Process Choreographer using the bpeconfig.jacl


script in interactive mode, or if you have not configured Business Process
Choreographer yet, there are no generated SQL scripts; you must customize a
copy of the standard SQL script.
a. Change to the Business Process Choreographer subdirectory where the
configuration scripts for your database are located.
v On Linux, and UNIX platforms:
Location on the product media: media_root or extract_directory/
dbscripts/ProcessChoreographer/DB2
Location after installation:install_root/dbscripts/
ProcessChoreographer/DB2
v On Windows platforms:
Location on the product media:media_root or extract_directory\
dbscripts\ProcessChoreographer\DB2
Location after installation:install_root\dbscripts\
ProcessChoreographer\DB2
b. Copy all *Observer.sql script files to your database server.
c. On the database server, change to the directory where you copied the script
files.

210

Business Process Choreographer

d. Create the table space:


1) Edit the createTablespace_Observer.sql script file according to the
instruction at the top of the file.
2) Run the table space creation script file, enter the command:
db2 -tf createTablespace_Observer.sql

3) Make sure that the script output contains no errors. If errors occur, you
can drop the table space using the dropTablespace_Observer.sql script
file.
e. Create the schema (tables, indexes, and views).
1) Edit the createSchema_Observer.sql script file according to the
instructions at the top of the file.
2) In the DB2 command-line processor, enter the command:
db2 -tf createSchema_Observer.sql

3) Make sure that the script output contains no errors. If you want to drop
the schema, use the dropSchema_Observer.sql script file.
3. If you want to use the Java implementation instead of the SQL implementation
of the Business Process Choreographer Observer UDFs perform Selecting
between Java and SQL user-defined functions on page 239.
4. Use the administrative console to create an XA data source that points to the
database, and test the connection.
Results
The database schema for the Business Process Choreographer Observer has been
prepared.
Related concepts
User-defined functions for Business Process Choreographer Observer on page
240
With Business Process Choreographer Observer you can run reports based on
timeslices or time intervals that result in SQL queries. To perform these reports,
Business Process Choreographer Observer requires some specific user-defined
functions (UDFs) to be installed in the database.
Related tasks
Selecting between Java and SQL user-defined functions on page 239
You can either use the setupEventCollector tool or run scripts to switch
between the Java-based and SQL-based user-defined functions (UDFs) in the
database for the Business Process Choreographer Observer.
Using the setupEventCollector tool to prepare a DB2 Universal database for the
Business Process Choreographer Observer:
This describes how to use an interactive menu-driven tool and
createTablespace_Observer.sql script to prepare a DB2 Universal database on Linux,
UNIX, and Windows platforms.
Before you begin
Your database must already exist.
Procedure
1. If you use a type 2 JDBC connection:
a. Prepare the command line environment:
Chapter 4. Configuring Business Process Choreographer

211

v On Linux and UNIX platforms, run the db2profile for your DB2 instance.
v On Windows, open a DB2 command window.
b. If your database is remote, catalog the database on a local DB2 instance.
2. Create the table space:
a. Change to the Business Process Choreographer subdirectory where the SQL
scripts for your database are located.
v On Linux and UNIX platforms, change to the directory
install_root/dbscripts/ProcessChoreographer/DB2.
v On Windows platforms, change to the directory install_root\dbscripts\
ProcessChoreographer\DB2.
b. Make a copy of the createTablespace_Observer.sql script file.
c. Edit your copy of the createTablespace_Observer.sql script file according to
the instruction at the top of the file.
d. Connect to the database using a user ID that has SYSCTRL or SYSADM
authority.
e. Run the table space creation script file, enter the command:
db2 -tf createTablespace_Observer.sql

f. Make sure that the script output contains no errors. If errors occur, you can
drop the table space using the dropTablespace_Observer.sql script file.
3. If you are using a user ID that is not a database administrator, make sure that it
has the following permissions:
GRANT CREATETAB, CONNECT, CREATE_EXTERNAL_ROUTINE ON DATABASE
TO USER user_name;
GRANT USE OF TABLESPACE tablespace_name TO USER user_name;

where user_name is the user ID, and tablespace_name is a list of all observer table
space names, as can be found in the script createTablespace_Observer.sql.
4. Change to the Business Process Choreographer directory where the
configuration scripts are located.
On Linux and UNIX platforms, enter:
cd install_root/ProcessChoreographer/config

On Windows platforms, enter:


cd install_root\ProcessChoreographer\config

5. Start the tool to set up the event collector, as described in setupEventCollector


tool on page 258.
6. Prepare the database:
a. When you see:
1)
2)
3)
4)
5)
6)

Prepare a database for the Event Collector and Observer


Install the Event Collector application
Remove the Event Collector application and related objects
Change configuration settings of an installed Event Collector
Drop the database schema of the Event Collector and Observer
Administer Observer related user-defined functions

0) Exit Menu

Select option 1 to prepare a database for the event collector and observer
applications.
b. When you see:
Prepare a database for the WebSphere Business Process Choreographer
Event Collector and Observer

212

Business Process Choreographer

Select the type of your database provider:


c)
d)
i)
8)
o)

Derby
DB2 Universal
DB2 iSeries
DB2 V8/V9 on z/OS
Oracle

0) Exit Menu

Enter d to select DB2 Universal.


c. The tool allows you to create an SQL file that you can give to your database
administrator to run, rather than running it with your current user ID.
When you see:
Do you want to create an SQL file only (delay database preparation)?
y) yes
n) no

v If you do not want to delay running the SQL, enter n.


v If you want to delay running the SQL, enter y. You will see:
Even if you want to delay the configuration,
your entered values can be checked within the database.
Do you want to perform these checks?
y) yes
n) no

If you want the values that you enter to be checked within the
database, enter y.
Otherwise enter n.
Depending on what you entered, you might not see all of the following
prompts. Skip any steps that you do not see.
d. If you see:
Specify the JDBC driver type to be used:
2) Connect using type 2 (using a native database client)
4) Connect using type 4 (directly via JDBC)

Specify the JDBC driver type:


v If you are using a native database client, enter 2 .
v Otherwise, enter 4 to select the type 4 JDBC driver.
e. If you see one of the following prompts:
Specify the name of your database: [BPEDB]
Specify the name of database in local catalog:

[BPEDB]

Either the database name, or an alias.


Note: The default value, BPEDB, is the same database that is used by
Business Process Choreographer. For a high-performance system, you
should use a different database. If you use a different database, it must exist
before you continue.
f. If you see:
Specify the hostname of the database server:

[localhost]

Enter the host name or IP address of your database server.


g. If you see:
Specify the port where the database server is listening:

[50000]

Chapter 4. Configuring Business Process Choreographer

213

Enter the port number for your database server.


h.
Specify the directory of your JDBC driver:

[D:\opt\SQLLIB\java]

Enter the directory where the db2jcc.jar and db2jcc_license_cu.jar JAR files
for the JDBC driver reside.
i. If you see:
Specify userid to connect to the database database_name [db2admin] :
Specify the password for userid user_ID :

Enter the user ID and password to connect to the database. The following is
displayed:
Trying to connect to database database_name, using user user_ID
Connected to database_name

j. If you see:
Specify the database schema to be used. [user_ID] :

Enter the database schema (the collection name) to be used for the database
objects. If you enter a space character or leave the field empty, the schema of
the user ID is used.
k. When you see:
Choose the implementation of the Observer user-defined functions.
Note: The Java UDFs are more precise, but they require a jar file
installed to the database.
Visit the Observer documentation for details.
1) Java
2) SQL
0) Exit Menu

v If you want to use the more precise Java-based user-defined functions


(UDFs), which requires that a JAR file is installed in the database, enter 1.
v If you want to use the less precise SQL-based UDFs, enter 2.
You see something similar to the following:
Checking for required tablespace(es) [OBSVRTS]
All required tablespaces were found.
Loading the jar file install_root\lib\bpcodbutil.jar into the database.
The jar file install_root\lib\bpcodbutil.jar was successfully installed.
The setup of the database completed successfully.

7. Use the administrative console to create an XA data source that points to the
database, and test the connection.
Results
The database schema for the Business Process Choreographer Observer has been
prepared.
Related concepts
User-defined functions for Business Process Choreographer Observer on page
240
With Business Process Choreographer Observer you can run reports based on
timeslices or time intervals that result in SQL queries. To perform these reports,
Business Process Choreographer Observer requires some specific user-defined
functions (UDFs) to be installed in the database.

214

Business Process Choreographer

Related tasks
Selecting between Java and SQL user-defined functions on page 239
You can either use the setupEventCollector tool or run scripts to switch
between the Java-based and SQL-based user-defined functions (UDFs) in the
database for the Business Process Choreographer Observer.

Preparing a DB2 for iSeries database for the Business Process


Choreographer Observer
You can either use scripts or an interactive tool to prepare the database.
Using an SQL script to prepare a DB2 for iSeries database for the Business
Process Choreographer Observer:
This describes how to use the createSchema_Observer.sql script in an i5/OS qshell
environment to prepare a DB2 for iSeries database.
Before you begin
Your collection must already exist. You can either use an existing collection, or
create a new one according to the database documentation. You must have
administrative authority (*ALLOBJ) for the database.
Procedure
1. If you configured Business Process Choreographer using the bpeconfig.jacl
script in batch mode or using the administrative console, use the generated
SQL script to create the Business Process Choreographer Observer database.
a. Locate the generated createSchema_Observer.sql SQL script.
v If you configured Business Process Choreographer in a network
deployment environment using the administrative console or by running
the bpeconfig.jacl script in connected mode, the
createSchema_Observer.sql script file is generated on the node of the
dmgr.
v If you configured Business Process Choreographer on a standalone server
using the administrative console or by running the bpeconfig.jacl script in
connected mode, the createSchema_Observer.sql script file is generated on
the node where you invoked wsadmin.
v If you configured Business Process Choreographer by running the
bpeconfig.jacl script in disconnected mode, the createSchema_Observer.sql
script file is generated on the node of the standalone server.
The generated script is: profile_root/dbscripts/ProcessChoreographer/
DB2iSeries/collection_name/createSchema_Observer.sql. Where:

b.

c.

d.
e.

collection_name
is the name of the collection.
If the database is remote, copy the generated script to the database host. If
you are not authorized to perform this, give your database administrator a
copy of the script and discuss your requirements with her.
Optional: You or your database administrator can customize the SQL script.
For example, to specify the allocation of disks and table spaces that you
planned in Planning the OBSRVRDB database on page 123.
Make sure that you are either in the DB2 command-line processor, or in a
qshell.
Run the SQL script on the database host by entering the following
command:
Chapter 4. Configuring Business Process Choreographer

215

db2 -tf createSchema_Observer.sql

2. If you configured Business Process Choreographer using the bpeconfig.jacl


script in interactive mode, or if you have not configured Business Process
Choreographer yet, there are no generated SQL scripts; you must customize a
copy of the standard SQL script.
a. In a qshell environment, locate the Business Process Choreographer
subdirectory where the configuration scripts for your database are located.
v Location on the product media: media_root or extract_directory/dbscripts/
ProcessChoreographer/DB2iSeries/createSchema.sql
v Location after installation:install_root/dbscripts/ProcessChoreographer/
DB2iSeries/createSchema.sql
b. Copy all *Observer.sql script files to your database server.
c. On the database server, change to the directory where you copied the script
files.
d. Create the schema (tables, indexes, and views).
1) Edit the createSchema_Observer.sql script file according to the
instruction at the top of the file.
2) Either in the DB2 command-line processor, or in a qshell, enter the
command:
db2 -tf createSchema_Observer.sql

3) Make sure that the script output contains no errors. If you want to drop
the schema, use the dropSchema_Observer.sql script file.
3. If you want to use the Java implementation of the necessary user-defined
functions (UDFs), perform Selecting between Java and SQL user-defined
functions on page 239.
4. Use the administrative console to create an XA data source that points to the
database, and test the connection.
Results
The database schema for the Business Process Choreographer Observer has been
prepared.
Related concepts
User-defined functions for Business Process Choreographer Observer on page
240
With Business Process Choreographer Observer you can run reports based on
timeslices or time intervals that result in SQL queries. To perform these reports,
Business Process Choreographer Observer requires some specific user-defined
functions (UDFs) to be installed in the database.
Related tasks
Selecting between Java and SQL user-defined functions on page 239
You can either use the setupEventCollector tool or run scripts to switch
between the Java-based and SQL-based user-defined functions (UDFs) in the
database for the Business Process Choreographer Observer.
Using the setupEventCollector tool to prepare a DB2 for iSeries database for the
Business Process Choreographer Observer:
This describes how to use an interactive menu-driven tool to prepare a DB2 for
iSeries database from within an i5/OS qshell environment.
About this task

216

Business Process Choreographer

You can either use an existing collection, or create a new one according to the
database documentation.
Procedure
1. Start a qshell environment.
2. Change to the Business Process Choreographer directory where the
configuration scripts are located. Enter:
cd install_root/ProcessChoreographer/config

3. Start the tool to set up the event collector, as described in setupEventCollector


tool on page 258.
4. Prepare the database:
a. When you see:
1)
2)
3)
4)
5)
6)

Prepare a database for the Event Collector and Observer


Install the Event Collector application
Remove the Event Collector application and related objects
Change configuration settings of an installed Event Collector
Drop the database schema of the Event Collector and Observer
Administer Observer related user-defined functions

0) Exit Menu

Select option 1 to prepare a database for the event collector and observer
applications.
b. When you see:
Prepare a database for the WebSphere Business Process Choreographer
Event Collector and Observer
Select the type of your database provider:
c)
d)
i)
8)
o)

Derby
DB2 Universal
DB2 iSeries
DB2 V8/V9 on z/OS
Oracle

0) Exit Menu

Enter i to select DB2 for iSeries.


c. The tool allows you to create an SQL file that you can give to your database
administrator to run, rather than running it with your current user ID.
When you see:
Do you want to create an SQL file only (delay database preparation)?
y) yes
n) no

v If you do not want to delay running the SQL, enter n.


v If you want to delay running the SQL, enter y. You will see:
Even if you want to delay the configuration,
your entered values can be checked within the database.
Do you want to perform these checks?
y) yes
n) no

If you want the values that you enter to be checked within the
database, enter y.
Otherwise enter n.
Depending on what you entered, you might not see all of the following
prompts. Skip any steps that you do not see.
Chapter 4. Configuring Business Process Choreographer

217

d. If you see:
Specify the JDBC driver to be used:
1) Connect using the IBM Toolbox for Java JDBC driver
2) Connect using the native JDBC driver
Your selection: [2]

v If you are configuring a remote database, enter 1 to select the IBM


Toolbox for Java JDBC driver.
v If you are configuring the local database, enter 2 to select the native JDBC
driver.
e. If you see:
Specify the name of database in local catalog:

[*LOCAL]

or
Specify the name of your database:

[*SYSBAS]

Enter the service identifier, or accept the default.


f. If you see:
Specify the hostname of the database server:

[localhost]

Enter the host name or IP address of your database server.


g. If you see:
Specify the directory of your JDBC driver:
[/QIBM/ProdData/HTTP/Public/jt400/lib]

Enter the directory where the JDBC driver JAR files reside.
v For the native driver (db2_classes.zip), this is typically
/QIBM/ProdData/Java400/ext.
v For the toolbox driver (jt400.jar), this is typically /QIBM/ProdData/
HTTP/Public/jt400/lib
h. If you see:
Specify userid to connect to the database database_name [db2admin] :
Specify the password for userid user_ID :

Enter the user ID and password to connect to the database.


i. If you see:
Specify the database schema to be used. [user_ID] :

Enter the database schema (the collection name) to be used for the database
objects. You must specify a schema that already exists. If you enter a space
character or leave the field empty, the schema of the user ID is used.
j. If you see:
Note: The Java UDFs are more precise, but they require a jar file
installed to the database.
Visit the Observer documentation for details.
1) Java
2) SQL
0) Exit Menu

v If you want to use the more precise Java-based user-defined functions


(UDFs), which requires that a JAR file is installed in the database, enter 1.
v If you want to use the less precise SQL-based UDFs, enter 2.

218

Business Process Choreographer

k. When the database has been successfully prepared, the following is


displayed:
The setup of the database completed successfully.

5. If you used a separate database (not BPEDB), then use the administrative
console to create an XA data source that points to the database, and test the
connection.
Results
The database schema for the Business Process Choreographer Observer has been
prepared.
Related concepts
User-defined functions for Business Process Choreographer Observer on page
240
With Business Process Choreographer Observer you can run reports based on
timeslices or time intervals that result in SQL queries. To perform these reports,
Business Process Choreographer Observer requires some specific user-defined
functions (UDFs) to be installed in the database.
Related tasks
Selecting between Java and SQL user-defined functions on page 239
You can either use the setupEventCollector tool or run scripts to switch
between the Java-based and SQL-based user-defined functions (UDFs) in the
database for the Business Process Choreographer Observer.
Using the setupEventCollector tool to prepare a DB2 for iSeries database from a
remote system:
This describes how to use an interactive menu-driven tool to prepare a DB2 for
iSeries database for the Business Process Choreographer Observer from a remote
Linux, Windows, or UNIX system.
About this task
You can either use an existing collection, or create a new one according to the
database documentation. The collection to be used must already exist.
Procedure
1. To prepare the database remotely, you need to download the IBM Toolbox
JDBC driver to connect to your iSeries machine. After downloading, note the
location of the jar file jt400.jar.
2. Start a command line environment.
3. Change to the Business Process Choreographer directory where the
configuration scripts are located.
v On Windows platforms, enter:
cd install_root\ProcessChoreographer\config

v On Linux and UNIX platforms, enter:


cd install_root/ProcessChoreographer/config

4. Start the tool to set up the event collector, as described in setupEventCollector


tool on page 258.
5. Prepare the database:
a. When you see:

Chapter 4. Configuring Business Process Choreographer

219

1)
2)
3)
4)
5)
6)

Prepare a database for the Event Collector and Observer


Install the Event Collector application
Remove the Event Collector application and related objects
Change configuration settings of an installed Event Collector
Drop the database schema of the Event Collector and Observer
Administer Observer related user-defined functions

0) Exit Menu

Select option 1 to prepare a database for the event collector and observer
applications.
b. When you see:
Prepare a database for the WebSphere Business Process Choreographer
Event Collector and Observer
Select the type of your database provider:
c)
d)
i)
8)
o)

Derby
DB2 Universal
DB2 iSeries
DB2 V8/V9 on z/OS
Oracle

0) Exit Menu

Enter i to select DB2 for iSeries.


c. The tool allows you to create an SQL file that you can give to your database
administrator to run, rather than running it with your current user ID.
When you see:
Do you want to create an SQL file only (delay database preparation)?
y) yes
n) no

v If you do not want to delay running the SQL, enter n.


v If you want to delay running the SQL, enter y. You will see:
Even if you want to delay the configuration,
your entered values can be checked within the database.
Do you want to perform these checks?
y) yes
n) no

If you want the values that you enter to be checked within the
database, enter y.
Otherwise enter n.
Depending on what you entered, you might not see all of the following
prompts. Skip any steps that you do not see.
d. If you see:
Specify the name of your database:

[*SYSBAS]

Enter the service identifier, or accept the default.


e. If you see:
Specify the hostname of the database server:

[localhost]

Enter the host name or IP address of your database server.


f. If you see:
Specify the directory of your JDBC driver:
[/QIBM/ProdData/HTTP/Public/jt400/lib]

220

Business Process Choreographer

Enter the directory where you downloaded the JDBC driver file jt400.jar.
g. If you see:
Specify userid to connect to the database database_name [db2admin] :
Specify the password for userid user_ID :

Enter the user ID and password to connect to the database.


h. If you see:
Specify the database schema to be used. [user_ID] :

Enter the database schema (the collection name) to be used for the database
objects. You must specify a schema that already exists. If you enter a space
character or leave the field empty, the schema of the user ID is used.
i. If you see:
Note: The Java UDFs are more precise, but they require a
jar file installed to the database.
Visit the Observer documentation for details.
1) Java
2) SQL
0) Exit Menu

v If you want to use the more precise Java-based user-defined functions


(UDFs), which requires that a JAR file is installed in the database, enter 1.
v If you want to use the less precise SQL-based UDFs, enter 2.
j. When the database has been successfully prepared, the following is
displayed:
The setup of the database completed successfully.

6. If you used a separate database (not BPEDB), then use the administrative
console to create an XA data source that points to the database, and test the
connection.
Results
The database schema for the Business Process Choreographer Observer has been
prepared.
Related concepts
User-defined functions for Business Process Choreographer Observer on page
240
With Business Process Choreographer Observer you can run reports based on
timeslices or time intervals that result in SQL queries. To perform these reports,
Business Process Choreographer Observer requires some specific user-defined
functions (UDFs) to be installed in the database.
Related tasks
Selecting between Java and SQL user-defined functions on page 239
You can either use the setupEventCollector tool or run scripts to switch
between the Java-based and SQL-based user-defined functions (UDFs) in the
database for the Business Process Choreographer Observer.

Preparing a DB2 for z/OS database for the Business Process


Choreographer Observer
You can prepare the database remotely or within the UNIX System Services.
Creating a DB2 for z/OS database for the Business Process Choreographer
Observer in USS:
Chapter 4. Configuring Business Process Choreographer

221

This describes how to use an interactive menu-driven tool, and the


createTablespace_Observer.sql script in UNIX System Services (USS) on a z/OS
machine, to create a DB2 for z/OS database.
Procedure
1. Prepare the DB2 environment:
a. Log on to the native z/OS environment.
b. If multiple DB2 systems are installed, decide which subsystem you want to
use.
c. Make a note of the IP port to which the DB2 subsystem is listening.
d. Determine the location name of the subsystem. To find out the location
name, either check on the DB2 Systems panel or select the DB2
administration menu option Execute SQL statements for your subsystem,
and enter the following SQL query:
select current server from sysibm.sysdummy1

e. Create a storage group and note the name, for example OBSVRSG.
f. If you want to use a new database, create a new database, for example,
named OBSVRDB. If you want, you can reuse an existing database and
storage group, for example, the Business Process Choreographer database,
BPEDB.
g. Decide which schema qualifier to use (_SQLID).
h. Decide which user ID, user_ID, will be used to set up the database. This is
not the user ID used to access the database at runtime.
i. Ensure that the user ID has the following rights to access the database and
storage group:
v Permission to use the storage group.
v Permission to use the database OBSVRDB.
v Permission to create table spaces within the database OBSVRDB.
v Permission to create tables within the database OBSVRDB.
j. If you intend to use the Java implementation of the Business Process
Choreographer user-defined functions (UDFs), ensure that the user ID also
has the following rights:
v Permission to perform a select on SYSIBM.SYSJAROBJECTS.
v Permission to execute the following stored procedures for the schema
SQLJ:
INSTALL_JAR
REMOVE_JAR
REPLACE_JAR
DB2_INSTALL_JAR
DB2_REMOVE_JAR
DB2_REPLACE_JAR
v Permission to execute packages belonging to the collection DSNJAR.
k. If you intend to use the Java implementation of the Business Process
Choreographer user-defined functions (UDFs), prepare the DB2 environment
to run Java user defined functions and interpreted Java routines. Perform
the following:
1) Enabling the DB2-supplied stored procedures and defining the tables
used by the DB2 Universal JDBC Driver
2) Setting up the environment for interpreted Java routines

222

Business Process Choreographer

Note the name of the WLM application environment created during this
procedure.
2. Log on to the USS.
3. Create the table space:
a. Change to the directory where the Business Process Choreographer
Observer database scripts for your database system are located. Depending
on your DB2 version, enter one of the following commands:
cd install_root/dbscripts/ProcessChoreographer/DB2zOSV8
cd install_root/dbscripts/ProcessChoreographer/DB2zOSV9

b. Edit the ASCII createTablespace_Observer.sql script. Replace @STOGRP@


with the storage group name and replace @DBNAME@ with the database name
(not the subsystem name).
c. Make sure that you are connected to your database, and run your
customized version of the script.
db2 -tf createTablespace_Observer.sql

4. Start the tool to set up the event collector, as described in setupEventCollector


tool on page 258.
5. Prepare the database: When you see:
1)
2)
3)
4)
5)
6)

Prepare a database for the Event Collector and Observer


Install the Event Collector application
Remove the Event Collector application and related objects
Change configuration settings of an installed Event Collector
Drop the database schema of the Event Collector and Observer
Administer Observer related user-defined functions

0) Exit Menu

a. Select option 1 to prepare a database for the event collector application.


b. Enter 8 to select your DB2 on z/OS version number. If you use DB2 for
z/OS V9, use the V8 options.
c. The tool allows you to create an SQL file that you can give to your database
administrator to run, rather than running it with your current user ID.
When you see:
Do you want to create an SQL file only (delay database preparation)?
y) yes
n) no

v If you do not want to delay running the SQL, enter n.


v If you want to delay running the SQL, enter y. You will see:
Even if you want to delay the configuration,
your entered values can be checked within the database.
Do you want to perform these checks?
y) yes
n) no

If you want the values that you enter to be checked within the
database, enter y.
Otherwise enter n.
Depending on what you entered, you might not see all of the following
prompts. Skip any steps that you do not see.
d. If you see:
Specify the database location name:
(as returned by SELECT CURRENT SERVER FROM SYSIBM.SYSDUMMY1):

Enter the location name of your database. This is the value you noted in
step 1d on page 222.
Chapter 4. Configuring Business Process Choreographer

223

e. If you see:
Specify the name of the database as known by the susbsystem [subsystem]

Enter the name that your database has in the subsystem on the z/OS host.
This is the value you noted in step 1f on page 222.
f. If you see:
Specify the hostname of the z/OS DB2 database server: [localhost]

Enter the hostname of your database server.


g. If you see:
Specify the port where the database subsystem is listening:

Enter the port number that is used by the database subsystem. This is the
value you noted in step 1c on page 222.
h. If you see:
Specify userid to connect to the database database_alias [db2admin] :

Enter the user ID to connect to the database . This is the user ID, user_ID,
described in step 1h on page 222.
i. If you see:
Specify the password for userid user_ID :

Enter the password for the user ID.


j. If you see:
Trying to connect to database database_alias, using user user_ID
Connected to database_alias
Specify the database schema to be used. [user_ID] :

Enter the database schema to be used for the database objects, or press Enter
to accept the default, which is the user ID that is used to connect to the
database. This is the schema qualifier _SQLID.
k. If you see:
Note: The Java UDFs are more precise, but they require a jar file
installed to the database.
Visit the Observer documentation for details.
1) Java
2) SQL
0) Exit Menu

v If you want to use the more precise Java-based user-defined functions


(UDFs), which requires that a JAR file is installed in the database, enter 1.
v If you want to use the less precise SQL-based UDFs, enter 2.
l. If you see:
Specify the DB2 storage group name to be used. [OBSVRSG] :

Enter the storage group name from step 1e on page 222, or press Enter to
accept the default value.
m. If you see:
Specify the WLM environment name where the UDF should run. [] :

Enter the WLM environment that you noted in step 1k on page 222.

224

Business Process Choreographer

n. After checking for the required table spaces and loading a JAR file into the
database, success is indicated by the following:
The setup of the database completed successfully.

6. Using the administrative console, create an XA data source that points to the
database.
Results
The database schema for the Business Process Choreographer Observer has been
prepared.
Related concepts
User-defined functions for Business Process Choreographer Observer on page
240
With Business Process Choreographer Observer you can run reports based on
timeslices or time intervals that result in SQL queries. To perform these reports,
Business Process Choreographer Observer requires some specific user-defined
functions (UDFs) to be installed in the database.
Related tasks
Selecting between Java and SQL user-defined functions on page 239
You can either use the setupEventCollector tool or run scripts to switch
between the Java-based and SQL-based user-defined functions (UDFs) in the
database for the Business Process Choreographer Observer.
Creating a DB2 for z/OS database for the Business Process Choreographer
Observer from a remote system:
This describes how to use an interactive menu-driven tool, and the
createTablespace_Observer.sql script on a Linux, UNIX, or Windows system to
create a DB2 for z/OS database.
Before you begin
You must have already installed WebSphere Process Server on a Linux, UNIX, or
Windows server.
Procedure
1. On the z/OS server that hosts the database:
a. Log on to the native z/OS environment.
b. If multiple DB2 systems are installed, decide which subsystem you want to
use.
c. Make a note of the IP port to which the DB2 subsystem is listening.
d. Create a storage group and note the name, for example OBSVRSG.
e. If you want to use a new database, create a new database, for example,
named OBSVRDB. If you want, you can reuse an existing database and
storage group, for example, the Business Process Choreographer database,
BPEDB.
f. Decide which schema qualifier to use (_SQLID).
g. Decide which user ID, user_ID, will be used to set up the database. This is
not the user ID used to access the database at runtime.
h. Ensure that the user ID has the following rights to access the database and
storage group:
v Permission to use the storage group.
Chapter 4. Configuring Business Process Choreographer

225

v Permission to use the database OBSVRDB.


v Permission to create table spaces within the database OBSVRDB.
v Permission to create tables within the database OBSVRDB.
i. If you intend to use the Java implementation of the Business Process
Choreographer user-defined functions (UDFs), ensure that the user ID also
has the following rights:
v Permission to perform a select on SYSIBM.SYSJAROBJECTS.
v Permission to execute the following stored procedures for the schema
SQLJ:
INSTALL_JAR
REMOVE_JAR
REPLACE_JAR
DB2_INSTALL_JAR
DB2_REMOVE_JAR
DB2_REPLACE_JAR
v Permission to execute packages belonging to the collection DSNJAR.
j. If you intend to use the Java implementation of the Business Process
Choreographer user-defined functions (UDFs), prepare the DB2 environment
to run Java user defined functions and interpreted Java routines. Perform the
following:
1) Enabling the DB2-supplied stored procedures and defining the tables
used by the DB2 Universal JDBC Driver
2) Setting up the environment for interpreted Java routines
Note the name of the WLM application environment created during this
procedure.
2. On the server that hosts the WebSphere Process Server:
a. Install a suitable DB2 client.
Note: If you plan to use a native DB2 client to connect to the remote
database (using a type 2 JDBC connection) make sure that you have DB2
Connect Gateway installed. DB2 Connect Gateway is part of the DB2 UDB
ESE package, but you can also install it separately.
b. If you are using a native DB2 client, catalog the remote database and verify
that you can establish a connection to it. Enter the following commands in a
DB2 command line window:
catalog tcpip node zosnode remote host_name server IP_port ostype mvs
catalog database location as database_alias at node zosnode
authentication dcs
catalog dcs database database_alias parms ,,INTERRUPT_ENABLED

where
zosnode
is a local alias for the remote z/OS node.
host_name
is either the TCP/IP address or alias of the remote z/OS machine.
IP_port
is the port number where the DB2 subsystem is listening.
database_alias
is the local alias to access the remote database.

226

Business Process Choreographer

location
is the remote DB2 location name. To find out the location name, log on
to TSO and enter the following SQL query on the selected subsystem
using one of the available query tools.
select current server from sysibm.sysdummy1

To verify that you can connect to the remote system, enter:


db2 connect to database_alias user userid using password

c. Change to the directory where the Business Process Choreographer


Observer database scripts for your database system are located:
v On Linux and UNIX platforms, depending on your DB2 version, enter
one of the following commands:
cd install_root/dbscripts/ProcessChoreographer/DB2zOSV8
cd install_root/dbscripts/ProcessChoreographer/DB2zOSV9

v On Windows platforms, depending on your DB2 version, enter one of the


following commands:
cd install_root\dbscripts\ProcessChoreographer\DB2zOSV8
cd install_root\dbscripts\ProcessChoreographer\DB2zOSV9

d. Edit the ASCII createTablespace_Observer.sql script. Replace @STOGRP@


with the storage group name and replace @DBNAME@ with the database name
(not the subsystem name).
e. Run your customized version of the script.
db2 -tf createTablespace_Observer.sql

If you want to drop the table space, use the dropTablespace_Observer.sql


script.
f. Change to the Business Process Choreographer subdirectory where the
configuration scripts are located.
On Linux and UNIX platforms, enter:
cd install_root/ProcessChoreographer/config

On Windows platforms, enter:


cd install_root\ProcessChoreographer\config

g. Start the tool to set up the event collector, as described in


setupEventCollector tool on page 258.
h. Select option 1 to prepare a database for the event collector application.
i. Enter 8 to select your DB2 on z/OS version number. If you use DB2 for
z/OS V9, use the V8 options.
j. The tool allows you to create an SQL file that you can give to your database
administrator to run, rather than running it with your current user ID. When
you see:
Do you want to create an SQL file only (delay database preparation)?
y) yes
n) no

v If you do not want to delay running the SQL, enter n.


v If you want to delay running the SQL, enter y. You will see:
Even if you want to delay the configuration,
your entered values can be checked within the database.
Do you want to perform these checks?
y) yes
n) no

If you want the values that you enter to be checked within the
database, enter y.
Chapter 4. Configuring Business Process Choreographer

227

Otherwise enter n.
Depending on what you entered, you might not see all of the following
prompts. Skip any steps that you do not see.
k. If you see:
Specify the JDBC driver type to be used:
2) Connect using type 2 (using a native database client)
4) Connect using type 4 (directly via JDBC)

Specify the JDBC driver type:


v If you are using a native database client, enter 2 .
v Otherwise, enter 4 to select the type 4 JDBC driver.
l. If you see:
Specify the name of database in local catalog:

[BPEDB]

Enter the name of your database as it is cataloged on the local DB2 client,
this is the value that you used for database_alias in step 2b on page 226.
m. If you see:
Specify the location name/connection target: []

Enter the location name of the subsystem to connect to.


Note: To determine the location name, log on with a SQL processor and
execute the following SQL statement:
SELECT CURRENT SERVER FROM SYSIBM.SYSDUMMY1

n. If you see:
Specify the name of the database as known by the subsystem: [OBSVRDB]

Enter the name by which the database is known within the subsystem on
the z/OS host.
o. If you see:
Specify the hostname of the database server: [localhost]
Specify the port where the database server is listening: [446]

Enter the host name and port number used by your z/OS database server.
p. If you see:
Specify the directory of your JDBC driver:

[]

Enter the directory where the db2jcc.jar and db2jcc_license_cisuz.jar JAR


files for the DB2 JDBC driver reside.
q. If you see:
Specify userid to connect to the database database_name [db2admin] :
Specify the password for userid user_ID :

Enter the user ID and password to connect to the database. This is the user
ID, user_ID, described in step 1g on page 225.
r. If you see:
Specify the database schema to be used. [user_ID] :

Enter the name of the database schema to use for the database objects.
s. If you see:

228

Business Process Choreographer

Note: The Java UDFs are more precise, but they require a jar file
installed to the database.
Visit the Observer documentation for details.
1) Java
2) SQL
0) Exit Menu

v If you want to use the more precise Java-based user-defined functions


(UDFs), which requires that a JAR file is installed in the database, enter 1.
v If you want to use the less precise SQL-based UDFs, enter 2.
t. If you see:
Specify the DB2 storage group name to be used. [OBSVRSG] :

Enter the storage group name from step 1d on page 225.


u. If you see:
Specify the WLM environment name where the UDF should run. [] :

Enter the WLM environment that you noted in step 1j on page 226. After
checking for the required table spaces and loading a JAR file into the
database, success is indicated by the following:
The setup of the database completed successfully.

3. Using the administrative console, create an XA data source that points to the
database.
Results
The database schema for the Business Process Choreographer Observer has been
prepared.
Related concepts
User-defined functions for Business Process Choreographer Observer on page
240
With Business Process Choreographer Observer you can run reports based on
timeslices or time intervals that result in SQL queries. To perform these reports,
Business Process Choreographer Observer requires some specific user-defined
functions (UDFs) to be installed in the database.
Related tasks
Selecting between Java and SQL user-defined functions on page 239
You can either use the setupEventCollector tool or run scripts to switch
between the Java-based and SQL-based user-defined functions (UDFs) in the
database for the Business Process Choreographer Observer.

Preparing a Derby database for the Business Process


Choreographer Observer
You can either use scripts or an interactive tool to prepare the database.
Using an SQL script to prepare a Derby database for the Business Process
Choreographer Observer:
This describes how to use the createSchema_Observer.sql script to prepare a Derby
database.
About this task

Chapter 4. Configuring Business Process Choreographer

229

You must create the schema for the Business Process Choreographer Observer
database. You can either create it in an existing database, or have the script file
create a new database for you.
Procedure
1. If you configured Business Process Choreographer using the bpeconfig.jacl
script in batch mode or using the administrative console, use the generated
SQL script to create the Business Process Choreographer Observer database.
a. Locate the generated SQL file.
v On Linux and UNIX platforms:
If you specified a schema qualifier, the generated script is located in
the directory: profile_root/dbscripts/ProcessChoreographer/Derby/
database_name/database_schema.
If you did not specify a schema qualifier, the generated script is
located in the directory: profile_root/dbscripts/
ProcessChoreographer/Derby/database_name.
v On Windows platforms:
If you specified a schema qualifier, the generated script is located in
the directory: profile_root\dbscripts\ProcessChoreographer\Derby\
database_name\database_schema\
If you did not specify a schema qualifier, the generated script is
located in the directory: profile_root\dbscripts\
ProcessChoreographer\Derby\database_name\
v On the i5/OS platform: The generated script is located in the directory:
profile_root/dbscripts/ProcessChoreographer/Derby/.
Where:
database_name
is the name of your database.

b.
c.
d.
e.

database_schema
is the name of the schema, if you are using one.
In a derby network server environment, copy the SQL script to the network
server.
Copy the JAR file bpcodbutil.jar, from the lib subdirectory of the install_root
directory to the same directory on your database server.
If you connect to an existing database using the embedded Derby driver,
stop the server and any other applications that use the database.
Run the script to create the schema. For example:
v To create a database named OBSVRDB, from the directory where the
database will be created, enter the command:
java -Dij.protocol=jdbc:derby:
-Dij.database=OBSVRDB;create=true
org.apache.derby.tools.ij
createSchema_Observer.sql

v For a database named OBSVRDB, which already exists, from the directory
where the database was created, enter the command:
java -Dij.protocol=jdbc:derby:
-Dij.database=OBSVRDB
org.apache.derby.tools.ij
createSchema_Observer.sql

230

Business Process Choreographer

2. If you configured Business Process Choreographer using the bpeconfig.jacl


script in interactive mode, or if you have not configured Business Process
Choreographer yet, there are no generated SQL scripts; you must customize a
copy of the standard SQL script.
a. Change to the Business Process Choreographer subdirectory where the
standard configuration scripts for your database are located.
v On Linux, UNIX, and i5/OS platforms
Location on the product media: media_root or extract_directory/
dbscripts/ProcessChoreographer/Derby
Location after installation:install_root/dbscripts/
ProcessChoreographer/Derby
v On Windows platforms:
Location on the product media:media_root or extract_directory\
dbscripts\ProcessChoreographer\Derby
Location after installation:install_root\dbscripts\
ProcessChoreographer\Derby
b. In a derby network server environment, copy the *Observer.sql scripts to
the network server.
c. Copy the JAR file bpcodbutil.jar, from the lib subdirectory of the install_root
directory to the same directory on your database server.
d. In a text editor, read the instructions in the header of the script file
createSchema_Observer.sql. If you want to create a new database, append
;create=true to the database name. For example, if your database name is
OBSVRDB, replace the parameter -Dij.database=OBSVRDB with
-Dij.database=OBSVRDB;create=true
Note: On Windows platforms, avoid using the Notepad editor, because it
does not display the file in a readable format.
e. If you connect to an existing database using the embedded Derby driver,
stop the server and any other applications that use the database.
f. Create the schema. From the directory where you created the database, run
the script file createSchema_Observer.sql as described in the header of the
script.
g. In case of errors, you can run the script file dropSchema_Observer.sql to
drop the schema.
3. Use the administrative console to create an XA data source that points to the
database, and test the connection.
Results
The database schema for the Business Process Choreographer Observer has been
prepared.
Using the setupEventCollector tool to prepare a Derby database for the Business
Process Choreographer Observer:
This describes how to use an interactive menu-driven tool, setupEventcollector, to
prepare a Derby database on any supported platform.
Procedure
1. Change to the Business Process Choreographer subdirectory where the
configuration scripts are located.
Chapter 4. Configuring Business Process Choreographer

231

On Linux, UNIX, and i5/OS platforms, enter:


cd install_root/ProcessChoreographer/config

On Windows platforms, enter:


cd install_root\ProcessChoreographer\config

2. If you connect to an existing database using the embedded Derby driver, stop
the server and any other applications that use the database. Plan to use the
-conntype none when starting the tool.
3. Start the tool to set up the event collector, as described in
setupEventCollector tool on page 258.
4. When you see:
1)
2)
3)
4)
5)
6)

Prepare a database for the Event Collector and Observer


Install the Event Collector application
Remove the Event Collector application and related objects
Change configuration settings of an installed Event Collector
Drop the database schema of the Event Collector and Observer
Administer Observer related user-defined functions

0) Exit Menu

Select option 1 to prepare a database for the event collector application. The
following menu is displayed:
Prepare a database for the WebSphere Business Process Choreographer
Event Collector and Observer
Select the type of your database provider:
c)
d)
i)
8)
o)

Derby
DB2 Universal
DB2 iSeries
DB2 V8/V9 on z/OS
Oracle

0) Exit Menu

5. Enter c to select Derby.


6. The tool allows you to create an SQL file that you can give to your database
administrator to run, rather than running it with your current user ID. When
you see:
Do you want to create an SQL file only (delay database preparation)?
y) yes
n) no

v If you do not want to delay running the SQL, enter n.


v If you want to delay running the SQL, enter y. You will see:
Even if you want to delay the configuration,
your entered values can be checked within the database.
Do you want to perform these checks?
y) yes
n) no

If you want the values that you enter to be checked within the database,
enter y.
Otherwise enter n.
Depending on what you entered, you might not see all of the following
prompts. Skip any steps that you do not see.
7. If you see:

232

Business Process Choreographer

Specify the JDBC driver type to be used:


1) Connect using the embedded JDBC driver
2) Connect using the network JDBC driver
Your selection: [1]

v To connect using the embedded JDBC driver, enter 1.


Important: While configuring the database using this driver, make sure that
no other application (including the WebSphere Process Server) is connected
to the database.
v To use the network JDBC driver, enter 2.
8. When you see: Specify the name of your database [database_name]
Enter the fully qualified path to the database.
Note: The default value, ...\BPEDB, is the same database that is used by the
Business Process Choreographer. For better performance, use a separate
database.
9. If you see:
Specify the database schema to be used. [APP] :

Enter the database schema name to be used for the database objects. If you
enter a space character or leave the field empty, the default schema, APP, is
used.
10. If you see:
Specify the hostname of the database server: [localhost]
Specify the port where the database server is listening: [1527]

Enter the host name and port number for your Derby network server.
11. If you see:
Specify the directory of your JDBC driver:

[B:\w\p\derby\lib]

v For the embedded JDBC driver, enter the directory where the derby.jar file
is located.
v For the network JDBC driver, enter the directory where the derbyclient.jar is
located.
12. If you see:
Specify userid to connect to the database database_name: []

v If the server requires authentication, enter a user ID that is authorized to


connect to your Derby network server.
v Otherwise, entering no value results in the user ID, dummy, being used. This
is because the Derby JDBC driver always requires a user ID to connect to a
network server.
13. If you see:
The application server must be stopped to update a Derby /
Cloudscape database.
This must be done outside wsadmin using stopServer server_name.
After the server is stopped, come back to this prompt and enter
c to continue.
Please stop the server server_name now.
Press c to continue, a to abort:

a. Stop the server, outside wsadmin, using the command:


stopServer server_name

Chapter 4. Configuring Business Process Choreographer

233

b. If you stopped the server, press c to continue. Otherwise, press a to return


to the main menu shown in step 4 on page 232.
14. If you see:
Specify the database schema to be used. [APP] :

Enter the name of schema to be used for the database objects, or press Enter
to use the default.
15. Make sure that you see the following message, which confirms that the
database was prepared successfully:
The setup of the database completed successfully.

16. If you see:


Restart the server now using startServer server_name.
After the server is up again, come back to this prompt and enter
c to continue.
Press c to continue, a to abort:

a. Start the server, using the command:


startServer server_name

b. Wait until the server has started, then back at this prompt, press c to
continue. Otherwise, press a to return to the main menu shown in step 4
on page 232.
Success is indicated by the message:
WASX7074I: Reconnect of SOAP connector to host localhost completed.

17. Use the administrative console to create an XA data source that points to the
database, and test the connection.
Results
The database schema for the Business Process Choreographer Observer has been
prepared.

Preparing an Oracle database for the Business Process


Choreographer Observer
You can either use scripts or an interactive tool to prepare the database.
Using SQL scripts to prepare an Oracle database for the Business Process
Choreographer Observer:
This describes how to use scripts to prepare an Oracle database.
About this task
Your database must already exist. You can either use an existing database, or create
a new one according to the database documentation.
Procedure
1. If you configured Business Process Choreographer using the bpeconfig.jacl
script in batch mode or using the administrative console, use the generated
SQL script to create the Business Process Choreographer Observer database.
a. Locate the generated SQL file.
v On Linux and UNIX platforms:
If you specified a schema qualifier, the generated script is:
profile_root/dbscripts/ProcessChoreographer/Oracle/
database_name/database_schema/createSchema_Observer.sql.

234

Business Process Choreographer

If you did not specify a schema qualifier, the generated script is:
profile_root/dbscripts/ProcessChoreographer/Oracle/
database_name/createSchema_Observer.sql.
v On Windows platforms:
If you specified a schema qualifier, the generated script is:
profile_root\dbscripts\ProcessChoreographer\Oracle\
database_name\database_schema\createSchema_Observer.sql
If you did not specify a schema qualifier, the generated script is:
profile_root\dbscripts\ProcessChoreographer\Oracle\
database_name\createSchema_Observer.sql
v On the i5/OS platform: The generated script is: profile_root/dbscripts/
ProcessChoreographer/Oracle/createSchema_Observer.sql.
b. Copy the generated script createSchema_Observer.sql to your database
server.
c.

Run the createSchema_Observer.sql script file, by entering the following


command:
sqlplus userID/password
@database_name@createSchema_Observer.sql

2. If you configured Business Process Choreographer using the bpeconfig.jacl


script in interactive mode, or if you have not configured Business Process
Choreographer yet, there are no generated SQL scripts; you must customize a
copy of the standard SQL script.
a. Change to the Business Process Choreographer subdirectory where the
configuration scripts for your database are located.
v On Linux, UNIX, and i5/OS platforms:
Location on the product media: media_root or extract_directory/
dbscripts/ProcessChoreographer/Oracle
Location after installation:install_root/dbscripts/
ProcessChoreographer/Oracle
v On Windows platforms:
Location on the product media:media_root or extract_directory\
dbscripts\ProcessChoreographer\Oracle
Location after installation:install_root\dbscripts\
ProcessChoreographer\Oracle
b. Copy all *Observer.sql script files to your database server.
c. Create the table space
1) Edit your copy of the createTablespace_Observer.sql script file
according to the instruction at the top of the file.
2) Run your copy of the createTablespace_Observer.sql script file, by
entering the following command:
sqlplus userID/password
@database_name@createTablespace_Observer.sql

3) Make sure that the script output contains no errors. If errors occur, you
can drop the table space using the dropTablespace_Observer.sql script
file.
d. Create the schema (tables, indexes, and views).
1) Edit your copy of the createSchema_Observer.sql script file according to
the instruction at the top of the file.
2) Run your copy of the createSchema_Observer.sql script file, by entering
the following command:
Chapter 4. Configuring Business Process Choreographer

235

sqlplus userID/password
@database_name@createSchema_Observer.sql

3) Make sure that the script output contains no errors. If you want to drop
the schema, use the dropSchema_Observer.sql script file.
3. If you want to use the Java-based Business Process Choreographer user-defined
functions:
a. Copy the JAR file bpcodbutil.jar, from the lib subdirectory of the
install_root directory to the directory that contains the SQL script file.
b. Install the JAR file that contains UDFs for Business Process Choreographer
Observer.
1) Log on to your database server as a user with Oracle administration
rights, and change to the directory where the JAR file bpcodbutil.jar is
located:
v If your database is on the same server as the application server,
change to the lib subdirectory of the install_root directory.
v If your database is not on the same machine as your application
server, change to the directory where you copied the JAR file
bpcodbutil.jar .
2) Run the Oracle loadjava utility to install the JAR file bpcodbutil.jar, by
entering the following command:
loadjava -user user/password@database
-schema schema_name
-resolve bpcodbutil.jar

where:
user, password, and database are valid values for user ID, password,
and the database name.
schema_name is the schema name under which the classes are to be
stored. This must be the same schema as the one that is used for the
Observer tables.
3) In case of problems, you can drop the JAR file using the command:
dropjava -user user/password@database
-schema schema_name bpcodbutil.jar

.
4. Use the administrative console to create an XA data source that points to the
database, and test the connection.
Results
The database schema for the Business Process Choreographer Observer has been
prepared.
Related concepts
User-defined functions for Business Process Choreographer Observer on page
240
With Business Process Choreographer Observer you can run reports based on
timeslices or time intervals that result in SQL queries. To perform these reports,
Business Process Choreographer Observer requires some specific user-defined
functions (UDFs) to be installed in the database.
Related tasks
Selecting between Java and SQL user-defined functions on page 239
You can either use the setupEventCollector tool or run scripts to switch

236

Business Process Choreographer

between the Java-based and SQL-based user-defined functions (UDFs) in the


database for the Business Process Choreographer Observer.
Using the setupEventCollector tool to prepare an Oracle database for the
Business Process Choreographer Observer:
This describes how to use an interactive menu-driven tool, and the
createTablespace_Observer.sql script to prepare an Oracle database.
About this task
Your database must already exist. You can either use an existing database, or create
a new one according to the database documentation.
Note: To create a remote Oracle database from an i5/OS platform, perform Using
SQL scripts to prepare an Oracle database for the Business Process Choreographer
Observer on page 234.
Procedure
1. On Linux and UNIX platforms: Add $ORACLE_HOME/bin to the PATH
variable.
2. Create the table space:
a. Change to the Business Process Choreographer subdirectory where the
standard configuration scripts for your database are located.
v On Linux and UNIX platforms, change to the directory
install_root/dbscripts/ProcessChoreographer/Oracle.
v On Windows platforms, change to the directory install_root\dbscripts\
ProcessChoreographer\Oracle.
b. Edit a copy of the createTablespace_Observer.sql script file according to the
instruction at the top of the file.
c. Run the table space creation script file according to the instructions at the
top of the file.
d. Make sure that the script output contains no errors. If errors occur, you can
drop the table space using the dropTablespace_Observer.sql script file.
3. Change to the Business Process Choreographer directory where the
configuration scripts are located.
On Linux and UNIX platforms, enter:
cd install_root/ProcessChoreographer/config

On Windows platforms, enter:


cd install_root\ProcessChoreographer\config

4. Start the tool to set up the event collector, as described in setupEventCollector


tool on page 258.
5. Prepare the database: When you see:
1)
2)
3)
4)
5)
6)

Prepare a database for the Event Collector and Observer


Install the Event Collector application
Remove the Event Collector application and related objects
Change configuration settings of an installed Event Collector
Drop the database schema of the Event Collector and Observer
Administer Observer related user-defined functions

0) Exit Menu

Perform the following:


Chapter 4. Configuring Business Process Choreographer

237

a. Select option 1 to prepare a database for the event collector and observer
applications. The following menu is displayed:
Prepare a database for the WebSphere Business Process Choreographer
Event Collector and Observer
Select the type of your database provider:
c)
d)
i)
8)
o)

Derby
DB2 Universal
DB2 iSeries
DB2 V8/V9 on z/OS
Oracle

0) Exit Menu

b. Enter o to select Oracle.


c. The tool allows you to create an SQL file that you can give to your database
administrator to run, rather than running it with your current user ID.
When you see:
Do you want to create an SQL file only (delay database preparation)?
y) yes
n) no

v If you do not want to delay running the SQL, enter n.


v If you want to delay running the SQL, enter y. You will see:
Even if you want to delay the configuration,
your entered values can be checked within the database.
Do you want to perform these checks?
y) yes
n) no

If you want the values that you enter to be checked within the
database, enter y.
Otherwise enter n.
Depending on what you entered, you might not see all of the following
prompts. Skip any steps that you do not see.
d. If you see:
Specify the database to be used.
Note: Database must already exist.
Specify the name of your database [BPEDB] :

Enter the SID name of the database.


e. If you see:
Specify the hostname where the oracle database resides: [localhost]

Enter the hostname or IP address of the database server.


f. If you see:
Specify the port where the oracle listener is listening: [1521]

Enter the port number for the Oracle listener.


g. If you see:
Specify userid to connect to the database database_name [system] :

Enter the user ID to connect to the database. The default is system.


h. If you see:
Specify the password for userid user_ID :

238

Business Process Choreographer

Enter the password for the user ID.


i. When you see:
Choose the implementation of the Observer user-defined functions.
Note: The Java UDFs are more precise, but they require a jar file
installed to the database.
Visit the Observer documentation for details.
1) Java
2) SQL
0) Exit Menu

v If you want to use the more precise Java-based user-defined functions


(UDFs), which requires that a JAR file is installed in the database, enter 1.
v If you want to use the less precise SQL-based UDFs, enter 2.
You see something similar to the following:
Trying to connect to database database_name, using user user_ID
Connected to database_name
Checking for required tablespace(es) [OBSVRTS, OBSVRLOB, OBSVRIDX]
All required tablespaces were found.
Loading the jar file install_root\lib\bpcodbutil.jar into the database.
The jar file install_root\lib\bpcodbutil.jar was successfully installed.
The setup of the database completed successfully.

6. Using the administrative console, create an XA data source that points to the
database.
Results
The database schema for the Business Process Choreographer Observer has been
prepared.
Related concepts
User-defined functions for Business Process Choreographer Observer on page
240
With Business Process Choreographer Observer you can run reports based on
timeslices or time intervals that result in SQL queries. To perform these reports,
Business Process Choreographer Observer requires some specific user-defined
functions (UDFs) to be installed in the database.
Related tasks
Selecting between Java and SQL user-defined functions
You can either use the setupEventCollector tool or run scripts to switch
between the Java-based and SQL-based user-defined functions (UDFs) in the
database for the Business Process Choreographer Observer.

Selecting between Java and SQL user-defined functions


You can either use the setupEventCollector tool or run scripts to switch between
the Java-based and SQL-based user-defined functions (UDFs) in the database for
the Business Process Choreographer Observer.
Related concepts
User-defined functions for Business Process Choreographer Observer on page
240
With Business Process Choreographer Observer you can run reports based on
timeslices or time intervals that result in SQL queries. To perform these reports,
Business Process Choreographer Observer requires some specific user-defined
functions (UDFs) to be installed in the database.
Chapter 4. Configuring Business Process Choreographer

239

User-defined functions for Business Process Choreographer


Observer
With Business Process Choreographer Observer you can run reports based on
timeslices or time intervals that result in SQL queries. To perform these reports,
Business Process Choreographer Observer requires some specific user-defined
functions (UDFs) to be installed in the database.
UDFs can be installed in either of the following implementations:
SQL implementation
Use the SQL implementation for UDFs that are implemented in plain SQL,
using the built-in time functions that are provided by the database system.
Installing the SQL implementation is easier than installing the Java
implementation because the SQL implementation requires to run provided
SQL scripts only. For these scripts, less administration rights are required
to install them. In addition, the SQL implementation has a higher
performance than the Java implementation. However, because of
limitations of the build-in time functions SQL implemented UDFs might
not be precise enough for your needs. For example, on DB2, the build-in
time function assumes that each month has the length of 30 days, which
might falsify your results.
SQL implementation is not available on Derby databases.
Java implementation
Use the Java implementation for UDFs that are implemented using the
Java language.
To install the Java implementation, use the mechanisms provided by the
database system. Java implemented UDFs grant precise reports. However,
installing the Java implementation requires more steps then installing the
SQL implementation, and it requires more administration rights on the
database. For example, on DB2 z/OS databases, a work load manager
(WLM) environment has to be set up to run the UDFs.
Depending on which way you choose to setup your database, the default
implementation varies:
v If you set up your database to use SQL scripts, or to use the create tables on first
touch feature, the SQL implementation is installed by default.
v If you set up your database to use the setupEventCollector tool, or to use the
Business Process Choreographer sample configuration in the Profile creation
wizard (only provided on Derby databases), the Java implementation is installed
by default.
The implementation of the UDFs can be changed after the initial setup. This is
described in Selecting between Java and SQL user-defined functions on page 239.
Related tasks
Selecting between Java and SQL user-defined functions on page 239
You can either use the setupEventCollector tool or run scripts to switch
between the Java-based and SQL-based user-defined functions (UDFs) in the
database for the Business Process Choreographer Observer.
Using an SQL script to prepare a DB2 for iSeries database for the Business
Process Choreographer Observer on page 215
This describes how to use the createSchema_Observer.sql script in an i5/OS
qshell environment to prepare a DB2 for iSeries database.

240

Business Process Choreographer

Using the setupEventCollector tool to prepare a DB2 for iSeries database for
the Business Process Choreographer Observer on page 216
This describes how to use an interactive menu-driven tool to prepare a DB2 for
iSeries database from within an i5/OS qshell environment.
Using the setupEventCollector tool to prepare a DB2 for iSeries database from
a remote system on page 219
This describes how to use an interactive menu-driven tool to prepare a DB2 for
iSeries database for the Business Process Choreographer Observer from a
remote Linux, Windows, or UNIX system.
Creating a DB2 for z/OS database for the Business Process Choreographer
Observer in USS on page 221
This describes how to use an interactive menu-driven tool, and the
createTablespace_Observer.sql script in UNIX System Services (USS) on a z/OS
machine, to create a DB2 for z/OS database.
Creating a DB2 for z/OS database for the Business Process Choreographer
Observer from a remote system on page 225
This describes how to use an interactive menu-driven tool, and the
createTablespace_Observer.sql script on a Linux, UNIX, or Windows system to
create a DB2 for z/OS database.
Using SQL scripts to prepare an Oracle database for the Business Process
Choreographer Observer on page 234
This describes how to use scripts to prepare an Oracle database.
Using the setupEventCollector tool to prepare an Oracle database for the
Business Process Choreographer Observer on page 237
This describes how to use an interactive menu-driven tool, and the
createTablespace_Observer.sql script to prepare an Oracle database.
Using SQL scripts to prepare a DB2 Universal database for the Business
Process Choreographer Observer on page 209
This describes how to use scripts to prepare a DB2 Universal database on
Linux, UNIX, and Windows platforms.
Using the setupEventCollector tool to prepare a DB2 Universal database for
the Business Process Choreographer Observer on page 211
This describes how to use an interactive menu-driven tool and
createTablespace_Observer.sql script to prepare a DB2 Universal database on
Linux, UNIX, and Windows platforms.
Related reference
setupEventCollector tool on page 258
Use setupEventCollector to interactively configure or remove the Business
Process Choreographer event collector application, to setup the database, and to
administer user-defined functions for the database. This tool uses wsadmin
scripting.

Using scripts to select between Java and SQL user-defined


functions
This describes how to use scripts to switch between the Java-based and SQL-based
user-defined functions (UDFs) in the database for the Business Process
Choreographer Observer.
About this task
You want to use the Java implementation instead of the SQL implementation of the
Business Process Choreographer Observer UDFs.
Procedure
Chapter 4. Configuring Business Process Choreographer

241

1. If you intend to use the Java implementation of the Business Process


Choreographer Observer user-defined functions (UDFs), copy the jar file
bpcodbutil.jar, from the lib subdirectory of the install_root directory to the
same directory on your database server.
2. If you intend to use the Java implementation of the Business Process
Choreographer Observer UDFs, install the jar file bpcodbutil.jar:
a. If you are not already connected to the database, connect to it by entering
the following command in a DB2 command-line processor:
db2 connect to databaseName

b. Install the jar file by entering the following command:


db2 call sqlj.install_jar(file:pathURL,schema.BPCODBUTIL)

where pathURL is a fully qualified URL to the jar file, and schema is the
name of the schema for the Business Process Choreographer database. For
example:
v On Linux and UNIX platforms, if the jar file is in the directory /tmp, you
must enter the command:
db2 call sqlj.install_jar(file:/tmp/bpcodbutil.jar,
schema.BPCODBUTIL)

v On Windows platforms, if the jar file is in the directory c:\tmp, you must
enter the command:
db2 call sqlj.install_jar(file:c:/tmp/bpcodbutil.jar,
schema.BPCODBUTIL)

Note: If you want to drop the jar file, use the following command:
db2 call sqlj.remove_jar(schema.BPCODBUTIL)

3. Drop the SQL implementation of the UDFs. Edit the


dropFunctions_Observer.sql script file according to the instruction at the top of
the file. For example, for DB2, in the DB2 command-line processor, enter the
command:
db2 -tf dropFunctions_Observer.sql

4. Create the Java implementation of the UDFs. Edit the


createFunctionsJava_Observer.sql script file according to the instruction at the
top of the file. For example, for DB2, in the DB2 command-line processor, enter
the command:
db2 -tf createFunctionsJava_Observer.sql

Results
The UDF implementation used has been switched.

Using the setupEventCollector tool to select between Java and


SQL user-defined functions
This describes how to use an interactive menu-driven tool to switch between the
Java-based and SQL-based user-defined functions (UDFs) in the database for the
Business Process Choreographer Observer.
About this task
For a Derby database, setupEventCollector always uses Java-based UDFs. For other
database types, it is the default for setupEventCollector to use Java-based UDFs,
but you can use the tool to switch to SQL-based UDFs. If you change your mind
again, you can use the tool to switch back to using Java-based UDFs.

242

Business Process Choreographer

Procedure
1. Start the tool to set up the event collector, as described in setupEventCollector
tool on page 258. You see the following menu:
1)
2)
3)
4)
5)
6)

Prepare a database for the Event Collector and Observer


Install the Event Collector application
Remove the Event Collector application and related objects
Change configuration settings of an installed Event Collector
Drop the database schema of the Event Collector and Observer
Administer Observer related user-defined functions

0) Exit Menu

2. Select option 6 to administer the observer-related user-defined functions. You


will see the following menu:
c)
d)
i)
8)
o)

Derby
DB2 Universal
DB2 iSeries
DB2 V8/V9 on z/OS
Oracle

3. If you are using either DB2 for Linux, UNIX, or Windows, or DB2 for z/OS,
select the option for your database version: d, or 8
a. When you see the following menu:
Specify which type should be used to connect to the Database:
2) Connect using type 2 (using a native DB2 client)
4) Connect using type 4 (directly via JDBC)

Select one of the following options:


2

For a type-2 JDBC connection, which uses a native DB2 client. In


this case, you are prompted to enter the following:
Database name
Database user ID
Password
Directory of your JDBC driver

For a type-4 JDBC driver, which connects directly. In this case, you
are prompted to enter the following:
Database name
Database server host name
Database server port number
Directory of your JDBC driver
Database user ID

Password
4. If you are using Oracle, select option o.
a. Enter the following connection information:
Database server host name
Database server port number
Database name
Database user ID
Password
Chapter 4. Configuring Business Process Choreographer

243

Directory of your JDBC driver


5. If a connection can be established to the database, you will see the menu for
administering the UDFs for the observer database:
6) Administer Observer related user-defined functions
1)
2)
3)
4)

Activate Java based user-defined functions


Activate SQL based user-defined functions
Determine current state
List, install or remove the jar file containing the java based functions

Note: The activate options do not apply for a Derby database.


a. If you want to activate the Java-based UDFs, select option 1.
1) When you see:
Specify the database schema to be used:

Enter the name of the database schema.


2) When you see:
WARNING: Switching the UDF implementation type may break any
running Observer applications. Continue anyway?
y) yes
n) no
Your selection:

If an important report is running, either enter n to not continue the


switch or wait until it has completed. Enter y to continue.
3) If you continue, you see something like the following:
Removing the user-defined functions ...
The jar file with jar_id DB2INST1.BPCODBUTIL is updated
with the current version.
Loading the jar file B:\w\p\lib\bpcodbutil.jar into the database.
The jar file BPCODBUTIL was successfully installed.
Creating the Java based user-defined functions ...

4) Success is indicated by the following message:


The setup of the database completed successfully.

b. If you want to activate the SQL-based UDFs, select option 2.


1) When you see:
Specify the database schema to be used:

Enter the name of the database schema.


2) When you see:
WARNING: Switching the UDF implementation type may break any
running Observer applications. Continue anyway?
y) yes
n) no
Your selection:

Enter y to continue or n not to continue.


3) If you see:
Removing the user-defined functions ...
Creating the SQL based user-defined functions ...

244

Business Process Choreographer

Do you also want to remove the jar file from the database?
y) yes
n) no
Your selection:

Enter y to remove the JAR file from the database, or n not to remove it.
4) Success is indicated by the following message:
The setup of the database completed successfully.

c. Optional: To determine whether the selected UDF implementation is Java or


SQL, and in the case that Java is active, to also verify whether the JAR file
is installed, select option 3. If, for example, the Java implementation is
active, you should get a message like the following:
The active UDF implementation is Java.
Tested functionality of the UDF, is working

d. Optional: To install or remove the JAR file that is required for the
Java-based UDFs, or to list all JAR files that are installed in the database,
select option 4, then when you see the following menu:
List, install or remove jar files containing the java based functions
1) Install the jar file containing the Observer functions
into the database
2) Remove the jar file containing the Observer functions
from the database
3) List installed jar files
0) Exit Menu

v Select option 1 to install the JAR file.


v Select option 2 to remove the JAR file.
v Select option 3 to list which JAR files are installed in the database.
v Select option 0 to exit from the menu.
e. Select option 0 repeatedly to return to the menu shown in step 1 on page
243.
Results
The Business Process Choreographer Observer database will use the UDFs that you
selected.

Configuring the Business Process Choreographer event


collector application
Install and configure the event collector application using an interactive tool or the
administrative console.
Before you begin
The Common Event Infrastructure (CEI) must be configured on the deployment
target where you want to install the event collector application.
About this task
To configure Business Process Choreographer event collector, perform one of the
following:

Chapter 4. Configuring Business Process Choreographer

245

Using the setupEventCollector tool to configure a Business


Process Choreographer event collector
This describes how to use an interactive menu-driven tool to install and configure
the event collector application on a server or cluster.
Procedure
1. Change to the Business Process Choreographer subdirectory where the
configuration scripts are located.
On Linux, UNIX, and i5/OS platforms, enter:
cd install_root/ProcessChoreographer/config

On Windows platforms, enter:


cd install_root\ProcessChoreographer\config

2. Start the tool to set up the event collector, as described in setupEventCollector


tool on page 258. For example, to start the tool to work with a server named
server1 enter one of the following commands:
On Linux and UNIX platforms:
setupEventCollector.sh -server server1

On i5/OS platforms:
setupEventCollector -server server1

On Windows platforms:
setupEventCollector.bat -server server1

You see the Commands Menu:


Commands Menu
1)
2)
3)
4)
5)
6)

Prepare a database for the Event Collector and Observer


Install the Event Collector application
Remove the Event Collector application and related objects
Change configuration settings of an installed Event Collector
Drop the database schema of the Event Collector and Observer
Administer Observer related user-defined funtions

0) Exit Menu

3. To install the Business Process Choreographer event collector application:


a. Select option 2. The following is displayed:
Create required objects and install the WebSphere Business Process
Choreographer Event Collector application ...

b. If you are installing on a standalone server, you see:


Working on node your_node_name, server your_server_name.

c. If you are installing the application on a deployment manager, you must


select the deployment target from a list of all available targets. For example:
Select the deployment target to install to:
1) Cluster cluster1
2) Node Node04, Server managed1
3) Node Node04, Server managed2
0) Exit Menu

d. While the tool searches for an existing event collector installation on the
deployment target, you will see something like:
Searching for an already installed Event Collector on deployment_target

e. If there is already an instance of the event collector application installed,


you see:

246

Business Process Choreographer

Do you want to overwrite the existing application?


o) Overwrite
a) Abort

v Enter o to overwrite the existing event collector application. All


installation values may be reentered and the event collector application is
updated.
v Enter a to exit without installing the event collector.
4. When you see:
Specify the JNDI name of the database where the WebSphere Business Process
Choreographer Event Collector should store the collected events.
Enter ? to get a list.
Your selection : [jdbc/BPEDB]

Enter the JNDI name that is used to connect to the database. You can also enter
? to get a list of all registered data sources. For example:
jdbc/BPEDB
jdbc/DefaultEJBTimerDataSource
jdbc/mediation/messageLog

5. When you see:


Specify the database schema to be used.
Enter a space character or leave empty to use the default schema of the
datasource. [] :

Enter the name of the schema for the database tables where the event collector
stores the events. To use the user ID that is specified in the authentication alias
of the data source definition as the schema, enter a space character or leave the
field empty.
All required objects are created and the enterprise application is installed.
Success is indicated by the message:
WebSphere Business Process Choreographer Event Collector
installed successfully!

6. If CEI logging is not enabled on the server, you see the following:
Checking if CEI event logging is enabled ...
Warning: The Business process container of server_name has CEI event
logging disabled.
To allow the Event Collector to work correctly, CEI event logging is required.
Do you want to enable the CEI event logging on server_name? (y/n)

v If you want the script to enable CEI logging on the named server, enter y.
v If you do not want the script to enable CEI logging on the named server,
enter n.
Note: It is important that CEI logging is enabled when you start working with
the Business Process Choreographer Observer.
7. When prompted:
Do you want to save the changes? (y/n)

If there were no error messages, enter y to save the configuration. If there were
errors, enter n to discard the changes and keep your original
configuration.Check the log file named setupEventCollector.log, which is
located in the logs directory of the profile.
For example, on Windows, if your profile is named myServer and your profiles
are stored in install_root\profiles, the log file is located in
install_root\profiles\myServer\logs.
8. Enter 0 to exit the menu.
Chapter 4. Configuring Business Process Choreographer

247

9. Activate the changes:


v If you specified the -conntype NONE option when starting the tool, your
changes become active after a server restart.
v If you did not specify the -conntype NONE option when starting the tool, and
you enabled CEI logging on the server during the installation of the Business
Process Choreographer event collector, use the administrative console to stop
and restart the BPEContainer application.
Results
The Business Process Choreographer event collector application is installed and
configured.

Using the administrative console to configure a Business


Process Choreographer event collector
This describes how to use the administrative console to install an instance of the
Business Process Choreographer event collector on a given server or cluster.
Before you begin
You have prepared the Business Process Choreographer Observer database.
Procedure
1. In the administrative console, navigate to the Business Process Choreographer
event collector configuration page: Click Servers Clusters cluster_name or
Servers Application servers server_name, then under Business Integration,
expand Business Process Choreographer, and click Business Process
Choreographer Event Collector.
2. To create a new configuration:
a. Enter or select values for the following fields:
v Database instance name.
v Schema name.
v Enable or clear the option to create the database tables the first time that
database is used.
v User name and password to connect to the database.
v Database servers host name or IP address.
v Port number for the database server.
v JDBC provider.
v Observation target:
Managed business process choreographer container
Existing event group name
Event group name
b. Click Apply to deploy the application.
c. In case of problems, check the SystemOut.log file. Otherwise, save the
changes to the master configuration.
d. Start the application by clicking Applications Enterprise Applications,
select the application BPCECollector_scope, where scope identifies the
deployment target, then click Start.
Results

248

Business Process Choreographer

The Business Process Choreographer event collector is configured.

Configuring the Business Process Choreographer Observer


application
You can either use a tool or the administrative console to configure the Business
Process Choreographer Observer application.
Before you begin
You have configured a Business Process Choreographer event collector.
About this task
To configure Business Process Choreographer Observer, perform one of the
following:

Using the setupObserver tool to configure a Business Process


Choreographer Observer
This describes how to use an interactive menu-driven tool to install an instance of
the Business Process Choreographer Observer application and configure it to
connect to the data source for a particular event collector.
Before you begin
You have prepared the Business Process Choreographer Observer database, and
used the administrative console to create a data source for it.
Procedure
1. Change to the Business Process Choreographer subdirectory where the
configuration scripts are located.
On Linux, UNIX, and i5/OS platforms, enter:
cd install_root/ProcessChoreographer/config

On Windows platforms, enter:


cd install_root\ProcessChoreographer\config

2. Start the tool to set up the observer, as described in setupObserver tool on


page 261. You see the menu:
1) Install the Observer application
2) Remove the Observer application and related objects
3) Change configuration settings of an installed Observer
0) Exit Menu

3. Select option 1 to install the Business Process Choreographer Observer. The


following is displayed:
Create required objects and install the WebSphere Business Process
Choreographer Observer application ...

4. If you are installing on a standalone server, you see:


Working on node your_node_name, server your_server_name.

5. If you are installing the application on a deployment manager, you must select
the deployment target from a list of all available targets. For example:
Select the deployment target to install to:
1) Cluster cluster1

Chapter 4. Configuring Business Process Choreographer

249

2) Node Node04, Server managed1


3) Node Node04, Server managed2
0) Exit Menu

6. When you see:


Specify the JNDI name of the database containing the event tables.
Enter ? to get a list.
Your selection : [jdbc/BPEDB]

Enter the JNDI name that is used to connect to the database. You can also enter
? to get a list of all registered data sources. For example:
jdbc/BPEDB
jdbc/DefaultEJBTimerDataSource
jdbc/mediation/messageLog

7. When you see:


Specify the database schema to be used.
Enter a space character or leave empty to use the default schema of the
datasource. [] :

Enter the name of the schema for the database tables where the event collector
stores the events. To use the user ID that is specified in the authentication alias
of the data source definition as the schema, enter a space character or leave the
field empty.
All required objects are created and the enterprise application is installed.
Success is indicated by the message:
WebSphere BPC Observer installed successfully!

8. When prompted: Do you want to save the changes? (y/n), if there were no
error messages, enter y to save the configuration. If there were errors, enter n to
discard the changes and keep your original configuration. Check the log file
named setupObserver.log, which is located in the logs directory of the profile.
For example, on Windows, if your profile is named myServer and your profiles
are stored in install_root\profiles, the log file is located in
install_root\profiles\myServer\logs.
9. Enter 0 to exit the menu.
Results
The Business Process Choreographer Observer is installed and configured.

Using the administrative console to configure a Business


Process Choreographer Observer
This describes how to use the administrative console to install an instance of the
Business Process Choreographer Observer application and configure it to connect
to the data source for a particular event collector.
Before you begin
You have configured the Business Process Choreographer event collector.
Procedure
1. In the administrative console, navigate to the Business Process Choreographer
Observer configuration page: Click Servers Clusters cluster_name or
Servers Application servers server_name, then under Business Integration,
expand Business Process Choreographer, and click Business Process
Choreographer Observer.

250

Business Process Choreographer

2. To create a new configuration:


a. Click Add.
b. Enter or select values for the following fields:
v Context root for this instance
v Visualize monitoring data from this Business Process Choreographer
event collector
c. Click Apply to deploy the application.
d. In case of problems, check the SystemOut.log file. Otherwise, save the
changes to the master configuration.
e. Start the application by clicking Applications Enterprise Applications,
select the application BPCObserver_scope, where scope identifies the
deployment target, then click Start.
Results
The Business Process Choreographer Observer configured and ready to use.
What to do next
You can configure more instances of the Business Process Choreographer Observer,
on the same or different deployment targets, by repeating this task. However, each
instance must connect to a different event collector data source.

Enabling logging for Business Process Choreographer


This describes how to enable Common Event Infrastructure (CEI) events for
Business Process Choreographer.
Before you begin
To monitor business process events with the Business Process Choreographer
Observer, your business process must be enabled to emit Common Event
Infrastructure (CEI) events. You specify this when modelling your business process.
In order to properly monitor a business process, at least the Process Started
event has to be emitted. For a list of CEI events that you can monitor using the
Business Process Choreographer Observer, see Business process events. For
information about how to enable a business process to emit CEI events, refer to the
WebSphere Integration Developer Information Center.
About this task
If you installed the Business Process Choreographer event collector on the same
deployment target as the one where Business Process Choreographer is configured,
you can use the setupEventCollector tool to enable CEI logging when you install
the application. If you installed the Business Process Choreographer event collector
using the administrative console you must enable CEI logging, either by using a
script or using the administrative console.
To use a Jython script to enable CEI logging for the Business Process
Choreographer, perform Using a script to enable logging for the Business Process
Choreographer on page 252.
To enable CEI logging for Business Process Choreographer, using the
administrative console, perform Enabling Common Base Events and the audit
trail, using the administrative console on page 288.
Chapter 4. Configuring Business Process Choreographer

251

Results
Common Event Infrastructure events for your business processes and activities will
be emitted, and can be received by a Business Process Choreographer event
collector.

Using a script to enable logging for the Business Process


Choreographer
This describes how to use the setStateObserver.py script to enable or disable
Common Event Infrastructure (CEI) or audit events for Business Process
Choreographer.

Location
The setStateObserver.py script is located in the Business Process Choreographer
config directory.

Running the script


To run the setStateObserver script:
On Linux and UNIX platforms, enter:
install_root/bin/wsadmin.sh
-f install_root/ProcessChoreographer/config/setStateObserver.py

On i5/OS platforms, enter:


install_root/bin/wsadmin
-f install_root/ProcessChoreographer/config/setStateObserver.py

On Windows platforms, enter:


install_root\bin\wsadmin.bat
-f install_root\ProcessChoreographer\config\setStateObserver.py

Parameters
The script file can take the following parameters:
-bfm
Optionally specifies that the enabling or disabling is to apply to the Business
Process Choreographers Business Flow Manager, which runs business
processes.
-cluster clusterName
Where clusterName is the name of the cluster. Do not specify this option in a
stand-alone server environment, nor if you specify the node and server.
-conntype NONE
Only include this option if the application server (for stand-alone) or
deployment manager is not running.
-enable ( CEI | AuditLog | CEI;AuditLog)
Optionally specifies whether to enable CEI logging, audit logging, or both.
-disable ( CEI | AuditLog | CEI;AuditLog)
Optionally specifies whether to disable CEI logging, audit logging, or both.
-htm
Optionally specifies that the enabling or disabling is to apply to the Business
Process Choreographers Human Task Manager, which runs human tasks.

252

Business Process Choreographer

-node nodeName
Where nodeName is the name of the node. Do not specify this option if you
specify a cluster.
-profileName profileName
Where profileName is the name of the profile to use.
-server serverName
Where serverName is the name of the server. Do not specify this option if you
specify a cluster.

Example
To enable CEI logging for business process events on server1, on Linux or UNIX
platforms:
wsadmin.sh -f setStateObserver.py -server server1 -enable CEI -bfm

Note: On Windows, use wsadmin.bat, and on i5/OS use wsadmin.

Changing configuration parameters for the Business Process


Choreographer Observer
Tuning the configuration parameters for the Business Process Choreographer
Observer and event collector applications is important to enable verification and
improve performance.

Changing default values


The default values are more suitable for a production system than for a test
system. If you are setting up the Business Process Choreographer for development
or testing, it makes sense to change the following configuration parameters before
you verify that the configuration is working:
v Change BPCEventTransformerEventCount to the value zero.
v Change BPCEventTransformerToleranceTime to the value one.
Making these changes ensures that even when events that are emitted at lower
rates than in a production system, the events become available in one minute.

Configuration parameters for the event collector


Tuning the numerical parameters affects how often the event transformer is
triggered, and the age at which events are made available to the Business Process
Choreographer Observer.

Chapter 4. Configuring Business Process Choreographer

253

Configuration parameter

Data type /
Units

Default value Description

ObserverSchemaName

String

not set

This identifies the database


schema that is used as a
prefix for all database
objects. If it is left empty, the
default is to use as a prefix,
the user ID that is used to
connect to the database. This
user ID is set as part of the
data source definition in the
administrative console. If
you specify a value for this
parameter, the user ID
specified at the data source
must have sufficient rights
to access the database
objects for this schema.

BPCEventTransformer
EventCount

Integer /
Events

500

The number of events after


which the event collector
triggers the transformer to
transform the collected
events into a format suitable
for the observer application.
When you are developing,
testing, and experimenting,
the default value is probably
too high, and causes events
to remain unobservable for a
long time. To make events
available faster, you can set
this value to zero. Every
future event will then
trigger the transformer, and
will become visible in the
observer. If you change the
value to zero, any past
events that have not yet
been transformed will be
transformed as soon as a
new event is generated.
Using a zero value is not
recommended for a
production system.

BPCEventTransformer
MaxWaitTime

254

Business Process Choreographer

Integer /
Minutes

10

The maximum time that can


pass before the transformer
is triggered - even though
the number of events
specified with
BPCEventTransformer
EventCount is not reached.

Configuration parameter

Data type /
Units

Default value Description

BPCEventTransformer
ToleranceTime

Integer /
Minutes

10

The minimum age in


minutes for an event to
become visible in the
observer. This enables
related events to be reliably
correlated. Using the value
zero should be avoided,
otherwise it is possible that
an event is processed before
the predecessor event has
arrived.
When you are developing,
testing, and experimenting,
the default value is probably
too high, and causes new
events to remain
unobservable for 10 minutes.
If you set this to the value 1,
all transformed events that
are more than one minute
old will be visible in the
observer.

ObserverCreateTables

Boolean

This parameter indicates if


the Observer schema should
be created when the EJB
connects to the database the
first time. Valid values are
true and false.

When the event collector receives a business relevant event from the Common
Event Infrastructure (CEI), the event is saved in the database. After some time has
passed and more events have been received, the transformer is started. The
transformer performs a batch transformation of the stored events and writes them
back to the database in a format that can be used for generating reports. Only
events that have been processed by the transformer are available for the observer
reports.
Every time that a new event is received by the event collector, if one or both of the
following conditions are true, then the transformer process is started:
v The number of events received since the transformer was last started is greater
than the value for BPCEventTransformerEventCount.
v The time since the transformer was last started is greater than the value of
BPCEventTransformerMaxWaitTime, in minutes.
If these values are made smaller, events will be available sooner for generating
reports, but there is some extra cost in transforming small numbers of events. This
requires a balance between having better transformation throughput, by processing
larger numbers of events, against the possible need to make the events available in
the observer database as fast as possible.
Each time that the transformer is started, it processes all events that are older than
BPCEventTransformerToleranceTime in minutes. It does not process more recent
events because events are not necessarily published in the order that they occur.
Chapter 4. Configuring Business Process Choreographer

255

The default setting of BPCEventTransformerToleranceTime assumes that no event


will take more than 10 minutes to be received and written to the event collector
table.

Changing configuration parameters for the event collector


To change event collector parameters, perform the following:
1. Start the tool to set up the event collector, as described in setupEventCollector
tool on page 258. You see the following menu:
1)
2)
3)
4)
5)
6)

Prepare a database for the Event Collector and Observer


Install the Event Collector application
Remove the Event Collector application and related objects
Change configuration settings of an installed Event Collector
Drop the database schema of the Event Collector and Observer
Administer Observer related user-defined functions

0) Exit Menu

2. Select option 4 to display the list of parameters that you can change:
1)
2)
3)
4)
5)

BPCEventTransformerEventCount
BPCEventTransformerMaxWaitTime
BPCEventTransformerToleranceTime
ObserverCreateTables
ObserverSchemaName

0) Exit Menu

3. Select the number of the parameter that you want to change. The parameters
name, description, type, units, and current value are displayed.
4. To change the specified value, enter a new value and press Enter. Pressing
Enter without a new value returns to the parameter list.
5. If you want to change the value of another parameter, repeat from step 3.
6. Enter 0 to exit the list. You are asked whether you want to save the changes.
7. To save all changes, enter y, otherwise enter n to discard all changes.
8. To activate the changes, restart the BPCECollector application.

Configuration parameters for the observer


The value for the ReportAtSnapshotRange parameter can have a big impact on the
performance of snapshot reports.

256

Business Process Choreographer

Configuration parameter

Data type /
Units

Default value Description

ObserverSchemaName

String

not set

This identifies the database


schema that is used as a
prefix for all database
objects. If it is left empty, the
default is to use as a prefix,
the user ID that is used to
connect to the database. This
user ID is set as part of the
data source definition in the
administrative console. If
you specify a value for this
parameter, the user ID
specified at the data source
must have sufficient rights
to access the database
objects for this schema. This
must match the value for the
event collector.

ReportAtSnapshotRange

Integer /
Days

60

A snapshot report is built by


evaluating all events that are
older than the qualifying
snapshot date and time.
ReportAtSnapshotRange
defines the period of time in
which events can be
included in a snapshot
report. Only events that
have been emitted within
this period are evaluated by
the snapshot report.
If this value is too high, a
very large number of events
might have to be processed,
and generating a report can
take a long time. Try setting
this value to the maximum
duration of a process
instance in your business
environment.

ObserverCreateTables

Boolean

This parameter indicates if


the Observer schema should
be created when the EJB
connects to the database the
first time. Valid values are
true and false.

Changing configuration parameters for the observer


To change observer parameters, perform the following:
1. Start the tool to set up the observer, as described in setupObserver tool on
page 261. You see the menu:

Chapter 4. Configuring Business Process Choreographer

257

1) Install the Observer application


2) Remove the Observer application and related objects
3) Change configuration settings of an installed Observer
0) Exit Menu

2. Select option 3 to display the list of parameters that you can change:
1) ReportAtSnapshotRange
2) ObserverCreateTables
3) ObserverSchemaName
0) Exit Menu

3. Select the number of the parameter that you want to change. The parameters
name, description, type, units, and current value are displayed.
4. To change the specified value, enter a new value and press Enter. Pressing
Enter without a new value returns to the parameter list.
5. If you want to change the value of another parameter, repeat from step 3.
6. Enter 0 to exit the list. You are asked whether you want to save the changes.
7. To save all changes, enter y, otherwise enter n to discard all changes.
8. To activate the changes, restart the BPCObserver application.

setupEventCollector tool
Use setupEventCollector to interactively configure or remove the Business Process
Choreographer event collector application, to setup the database, and to administer
user-defined functions for the database. This tool uses wsadmin scripting.

Location
This tool is located in the Business Process Choreographer subdirectory for
configuration scripts:
On Linux, UNIX, and i5/OS platforms: install_root/ProcessChoreographer/config.
On Windows platforms: install_root\ProcessChoreographer\config.

Restrictions
v In a network deployment environment, you must start the tool on the
deployment manager node, using the -profileName option to specify the
deployment manager profile .
v This tool is only available in English.
v On i5/OS, you must run the tool using qshell.

Parameters
[-conntype SOAP | RMI | JMS | NONE]
[-user userID -password password]
[-profileName profileName]
( [-node nodeName] [-server serverName] ) | ( -cluster clusterName )
[-remove [-silent]]

Where:
-conntype SOAP | RMI | JMS | NONE
The connection mode that wsadmin tool uses. In a standalone server
environment only include the -conntype NONE option if the application server
is not running. In a network deployment environment, only include -conntype
NONE option if the deployment manager is not running.

258

Business Process Choreographer

-user userID -password password


If global security is enabled, also provide a valid user ID and password for the
tool to use.
-profileName profileName
If you are not configuring the default profile, provide the name of the profile
that you want to configure.
-node nodeName
The name of the node. This parameter is optional. The default value is the
local node.
-server serverName
The name of the server. This parameter is optional.
-cluster clusterName
The cluster name clusterName . This parameter is optional.
-remove
Specify this option to remove the event collector application. If you do not
specify this option, the default is that the application will be configured.
-silent
This option can only be used with the remove option. It causes the tool to not
output any prompts. This parameter is optional.
Note: If you do not specify the -node, -server, nor -cluster parameters, you will be
prompted for the deployment target during configuration.

Example: Starting the tool


To start the tool to work with a server named server1 enter one of the following
commands.
On Linux and UNIX platforms:
setupEventCollector.sh -server server1

On i5/OS platforms:
setupEventCollector -server server1

On Windows platforms:
setupEventCollector.bat -server server1

You will see the Commands menu:


1)
2)
3)
4)
5)
6)

Prepare a database for the Event Collector and Observer


Install the Event Collector application
Remove the Event Collector application and related objects
Change configuration settings of an installed Event Collector
Drop the database schema of the Event Collector and Observer
Administer Observer related user-defined functions

0) Exit Menu

Using the tool


How to use this tool for particular tasks is described in the following topics.
Related concepts
User-defined functions for Business Process Choreographer Observer on page
240
With Business Process Choreographer Observer you can run reports based on
timeslices or time intervals that result in SQL queries. To perform these reports,
Chapter 4. Configuring Business Process Choreographer

259

Business Process Choreographer Observer requires some specific user-defined


functions (UDFs) to be installed in the database.
Related tasks
Configuring the Business Process Choreographer event collector application
on page 245
Install and configure the event collector application using an interactive tool or
the administrative console.
Using the setupEventCollector tool to prepare a DB2 Universal database for
the Business Process Choreographer Observer on page 211
This describes how to use an interactive menu-driven tool and
createTablespace_Observer.sql script to prepare a DB2 Universal database on
Linux, UNIX, and Windows platforms.
Using the setupEventCollector tool to prepare a DB2 for iSeries database for
the Business Process Choreographer Observer on page 216
This describes how to use an interactive menu-driven tool to prepare a DB2 for
iSeries database from within an i5/OS qshell environment.
Creating a DB2 for z/OS database for the Business Process Choreographer
Observer in USS on page 221
This describes how to use an interactive menu-driven tool, and the
createTablespace_Observer.sql script in UNIX System Services (USS) on a z/OS
machine, to create a DB2 for z/OS database.
Creating a DB2 for z/OS database for the Business Process Choreographer
Observer from a remote system on page 225
This describes how to use an interactive menu-driven tool, and the
createTablespace_Observer.sql script on a Linux, UNIX, or Windows system to
create a DB2 for z/OS database.
Using the setupEventCollector tool to prepare a Derby database for the
Business Process Choreographer Observer on page 231
This describes how to use an interactive menu-driven tool, setupEventcollector,
to prepare a Derby database on any supported platform.
Using the setupEventCollector tool to prepare an Oracle database for the
Business Process Choreographer Observer on page 237
This describes how to use an interactive menu-driven tool, and the
createTablespace_Observer.sql script to prepare an Oracle database.
Selecting between Java and SQL user-defined functions on page 239
You can either use the setupEventCollector tool or run scripts to switch
between the Java-based and SQL-based user-defined functions (UDFs) in the
database for the Business Process Choreographer Observer.
Using a script to remove the Business Process Choreographer configuration
on page 271
Use this task to remove the Business Flow Manager, Human Task Manager,
Business Process Choreographer Explorer and Business Process Choreographer
Observer configuration, and the associated resources from a server or cluster.
Related reference
Changing configuration parameters for the Business Process Choreographer
Observer on page 253
Tuning the configuration parameters for the Business Process Choreographer
Observer and event collector applications is important to enable verification
and improve performance.

260

Business Process Choreographer

setupObserver tool
Use setupObserver to interactively configure or remove the Business Process
Choreographer Observer application, or to change configuration parameters. This
tool uses wsadmin scripting.

Location
This tool is located in the Business Process Choreographer subdirectory for
configuration scripts:
On Linux, UNIX, and i5/OS platforms: install_root/ProcessChoreographer/config.
On Windows platforms: install_root\ProcessChoreographer\config.

Restrictions
v In a network deployment environment, you must start the tool on the
deployment manager node, using the -profileName option to specify the
deployment manager profile .
v This tool is only available in English.
v On i5/OS, you must run the tool using qshell.

Parameters
[-conntype SOAP | RMI | JMS | NONE]
[-user userID -password password]
[-profileName profileName]
( [-node nodeName] [-server serverName] ) | ( -cluster clusterName )
[-remove [-silent]]

Where:
-conntype SOAP | RMI | JMS | NONE
The connection mode that wsadmin tool uses. In a standalone server
environment only include the -conntype NONE option if the application server
is not running. In a network deployment environment, only include -conntype
NONE option if the deployment manager is not running.
-user userID -password password
If global security is enabled, also provide a valid user ID and password for the
tool to use.
-profileName profileName
If you are not configuring the default profile, provide the name of the profile
that you want to configure.
-node nodeName
The name of the node. This parameter is optional. The default value is the
local node.
-server serverName
The name of the server. This parameter is optional.
-cluster clusterName
The cluster name clusterName . This parameter is optional.
-remove
Specify this option to remove the event collector application. If you do not
specify this option, the default is that the application will be configured.

Chapter 4. Configuring Business Process Choreographer

261

-silent
This option can only be used with the remove option. It causes the tool to not
output any prompts. This parameter is optional.
Note: If you do not specify the -node, -server, nor -cluster parameters, you will be
prompted for the deployment target during configuration.

Example: Starting the tool


To start the tool to work with a server named server1 enter one of the following
commands.
On Linux and UNIX platforms:
setupObserver.sh -server server1

On i5/OS platforms:
setupObserver -server server1

On Windows platforms:
setupObserver.bat -server server1

You will see the Commands menu:


1) Install the Observer application
2) Remove the Observer application and related objects
3) Change configuration settings of an installed Observer
0) Exit Menu

Using the tool


How to use this tool for particular tasks is described in the following topics.
Related tasks
Using the setupObserver tool to configure a Business Process Choreographer
Observer on page 249
This describes how to use an interactive menu-driven tool to install an instance
of the Business Process Choreographer Observer application and configure it to
connect to the data source for a particular event collector.
Using a script to remove the Business Process Choreographer configuration
on page 271
Use this task to remove the Business Flow Manager, Human Task Manager,
Business Process Choreographer Explorer and Business Process Choreographer
Observer configuration, and the associated resources from a server or cluster.
Related reference
Changing configuration parameters for the Business Process Choreographer
Observer on page 253
Tuning the configuration parameters for the Business Process Choreographer
Observer and event collector applications is important to enable verification
and improve performance.

Verifying the Business Process Choreographer Observer


After installing and configuring the Business Process Choreographer Observer,
verify that the observer is working correctly.
Before you begin
Initially, the Business Process Choreographer Observer database is empty.

262

Business Process Choreographer

Procedure
1. Perform actions that will generate business events, for example, use the
Business Process Choreographer Explorer to start a process instance.
2. In a browser, start Business Process Choreographer Observer by opening the
URL http://host:port/context_root. Where host is the name of the host where
your application server is running, port is the port number for your application
server (the default is 9080), and context_root is typically bpcobserver.
3. Verify that the events you expect to be available are displayed. If you see no
events, wait a few minutes, restart the event collector application, and then
refresh your browser view.
Note: Using the default values for BPCEventTransfomerMaxWaitTime and
BPCEventTransfomerToleranceTime, it could take up to 20 minutes until the
transformer is triggered and the events in the event collector table are old
enough to be processed and made available. For information about these
parameters, including how to change them and suggested values for testing
purposes, see Changing configuration parameters for the Business Process
Choreographer Observer on page 253.
4. In case of problems, see Troubleshooting Business Process Choreographer
Observer on page 639.
Results
The Business Process Choreographer Observer is working.

Configuring a remote client application


Configuring a remote Business Process Choreographer client application that runs
on a WebSphere Process Server client installation.
Before you begin
You have performed Planning for a remote client application on page 100, and
know whether you are creating the single-cell scenario or the cross-cell
scenario.
Procedure
1. For the single-cell scenario, where the WebSphere Process Server client
installation is in the same cell as the Business Process Choreographer server or
cluster that the client connects to, perform the following:
a. Install and configure the WebSphere Process Server client:
1) Install the WebSphere Process Server client using the Client installation
option.
Note: If you want to use the WebSphere Process Server client in a
cluster, then you must install the WebSphere Process Server client on all
WebSphere Application Server installations that host cluster members.
2) If the profiles do not yet exist, perform the following:
a) Start the profile management tool and select Custom profile.
b) Federate the profile into the WebSphere Process Server cell. You can
also perform this action later, using the addNode command.

Chapter 4. Configuring Business Process Choreographer

263

c) Using the administrative console, create an application server using


the WebSphere default server template on the WebSphere Process
Server clients node.
b. Optional: Configure the Business Process Choreographer Explorer on the
application server in the WebSphere Process Server client using either the
administrative console or the clientconfig.jacl script. For the Business
Process Choreographer container target, make sure that you select the
WebSphere Process Server server or cluster that hosts the Business Flow
Manager and Human Task Manager.
c. Optional: Install and configure a custom client application.
1) Install the custom client application on the application server in the
WebSphere Process Server client installation.
2) Edit the custom client applicationss EJB bindings:
a) Using the administrative console, click Applications Enterprise
Application.
b) Click on your custom client application.
c) Under References, select EJB references. You will see the resource
references specified by your client application.
d) Locate the references to the Business Process Choreographer API
EJBs. You will see the default resource reference names and the
following JNDI names for the target resources:
ejb/BusinessFlowManagerHome
ejb/HumanTaskManagerHome

com/ibm/bpe/api/BusinessFlowManagerHome
com/ibm/task/api/HumanTaskManagerHome

e) Change the target resource JNDI names to values where the Business
Flow Manager and Human Task Manager API are located in your
cell:
v If Business Process Choreographer is configured on another server
in the same cell, the setting has the following structure:
cell/nodes/nodename/servers/servername/com/ibm/bpe/api/BusinessFlowManagerHome
cell/nodes/nodename/servers/servername/com/ibm/task/api/HumanTaskManagerHome

v If Business Process Choreographer is configured on a cluster in the


same cell, the setting looks like:
cell/clusters/clustername/com/ibm/bpe/api/BusinessFlowManagerHome
cell/clusters/clustername/com/ibm/task/api/HumanTaskManagerHome

3) Save and synchronize your changes.


4) Restart your client application.
d. The default configuration of the Remote Artifact Loader (RAL) allows the
unsecured transmission of artifacts between the client and the server.
2. For a cross-cell scenario, where the WebSphere Process Server client is not
located in the cell that has the managed server or cluster with Business Process
Choreographer configured on it. You can install the WebSphere Process Server
client on any WebSphere Application Server installation that hosts standalone
profiles or managed profiles for a different network deployment cell. As a
minimum, this network deployment cell only requires a WebSphere Application
Server deployment manager. To setup your WebSphere Process Server client
installation in this kind of environment and configure it to access the cell with
the Business Process Choreographer configuration, perform the following:
a. Install and configure the WebSphere Process Server client:
1) Install the WebSphere Process Server client using the Client installation
option.

264

Business Process Choreographer

Note: If you want to use the WebSphere Process Server client in a


cluster, then you must install the WebSphere Process Server client on all
WebSphere Application Server installations that host cluster members.
2) If the profiles do not yet exist, perform the following:
a) Start the profile management tool and select Custom profile.
b) Federate the profile into the WebSphere Process Server cell. You can
also perform this action later, using the addNode command.
c) Using the administrative console, create an application server using
the WebSphere default server template on the WebSphere Process
Server clients node.
b. Optional: Install and configure a custom client application.
1) Make sure the custom client application uses the Business Process
Choreographer EJB APIs.
2) Install the custom client application on the application server or cluster
in the WebSphere Process Server client installation.
c. Define a new indirect namespace binding (or bindings) to connect to the
cluster or server where Business Process Choreographer is configured:
1) Using the administrative console on the client cell, click Environment
Naming Name Space Bindings.
2) For Scope, select the cell.
3) Depending on whether the client application uses one or both of the
Business Flow Manager EJB API and the Human Task Manager EJB API,
perform the following steps once or twice to create a new binding for
one or both of the EJB APIs:
a) Click New.
b) For the Binding Type, select Indirect. In the next screen, specify the
following properties:
i. A unique binding identifier name. Although you are free to
choose a unique name, for consistency with the service
component architecture (SCA), you can derive a valid name from
the name space by replacing the forward slashes in the name
space with underscore characters. For example, the name space
bpc/remoteCellName_remoteNode_remoteServer/com/ibm/bpe/api/BusinessFlowManagerHome

becomes the binding ID name


bpc_remoteCellName_remoteNode_remoteServer_com_ibm_bpe_api_BusinessFlowManagerHome

ii. The name space of the client to be used for the binding. For
consistency, consider using the following convention:
v If the remote Business Process Choreographer configuration is
on a server: bpc/remoteCellName_remoteNode_remoteServer/
com/ibm/bpe/api/BusinessFlowManagerHome or
bpc/remoteCellName_remoteNode_remoteServer/com/ibm/task/
api/HumanTaskManagerHome
v If the remote Business Process Choreographer configuration is
on a cluster: bpc/remoteCellName_remoteCluster/com/ibm/bpe/
api/BusinessFlowManagerHome or bpc/
remoteCellName_remoteCluster/com/ibm/task/api/
HumanTaskManagerHome
iii. The provider URL property for the naming server that is used by
the server or cluster, where the Business Process Choreographer
configuration exists that the client will connect to. For example,
corbaloc:iiop://myremotehostname:2809. Make sure that the
Chapter 4. Configuring Business Process Choreographer

265

bootstrap port matches the BOOTSTRAP_ADDRESS of the


server (or one of the members of the cluster) where Business
Process Choreographer is hosted.
c) Specify the target resource JNDI name where the Business Flow
Manager API or Human Task Manager API is located.
v If Business Process Choreographer is configured on a server, the
setting has the following structure:
cell/nodes/nodename/servers/servername/com/ibm/bpe/api/BusinessFlowManagerHome
cell/nodes/nodename/servers/servername/com/ibm/task/api/HumanTaskManagerHome

v If Business Process Choreographer is configured on a cluster, the


setting looks like:
cell/clusters/clustername/com/ibm/bpe/api/BusinessFlowFlowManagerHome
cell/clusters/clustername/com/ibm/task/api/HumanTaskManagerHome

4) Using the administrative console on the client system:


a) Click Applications Enterprise Applications
client_application_name.
b) In the References section, select EJB references.
c) There will be one Target Resource JNDI Name field for reach name
space that you defined. Enter the JNDI name or names that you
specified in step 2c3bii on page 265 for the for the Business Flow
Manager, Human Task Manager, or both.
d) Save and synchronize your changes.
e) Restart your client application.
Results
You have configured a remote Business Process Choreographer client application
that uses a WebSphere Process Server client installation.
Related concepts
Comparison of the programming interfaces for interacting with business
processes and human tasks on page 389
Enterprise JavaBeans (EJB), Web service, and Java Message Service (JMS)
generic programming interfaces are available for building client applications
that interact with business processes and human tasks. Each of these interfaces
has different characteristics.
Related tasks
Configuring Business Process Choreographer Explorer on page 202
You can either run a script or use the administrative console to configure
Business Process Choreographer Explorer.
Chapter 10, Developing client applications for business processes and tasks,
on page 389
You can use a modeling tool to build and deploy business processes and tasks.
These processes and tasks are interacted with at runtime, for example, a process
is started, or tasks are claimed and completed. You can use Business Process
Choreographer Explorer to interact with processes and tasks, or the Business
Process Choreographer APIs to develop customized clients for these
interactions.
Accessing the remote interface of the session bean on page 392
An EJB client application accesses the remote interface of the session bean
through the remote home interface of the bean.
Related information
Installing the software

266

Business Process Choreographer

Starting the Profile Management Tool

Activating Business Process Choreographer


After configuring Business Process Choreographer, you must restart the affected
server or cluster.
About this task
To activate Business Process Choreographer:
Procedure
1. If you configured Business Process Choreographer on a server, restart the
server.
2. If you configured Business Process Choreographer on a cluster, restart the
cluster.
3. Make sure that there are no error messages in the SystemOut.log file for the
application server. On a cluster, check the log for all application servers in the
cluster.
4. Verify that the Business Flow Manager and Human Task Manager applications
have started successfully: In the administrative console, select Applications
Enterprise Applications and verify that the applications with names starting
with BPEContainer_scope and TaskContainer_scope have started.
Where, the value of scope is nodeName_serverName, if you configured Business
Process Choreographer on an application server, or the clusterName if you
configured Business Process Choreographer on a cluster.
Results
Business Process Choreographer is running.
What to do next
You are ready to verify that Business Process Choreographer is working.

Verifying that Business Process Choreographer works


Run the Business Process Choreographer installation verification application.
Procedure
1. Using either the administrative console or the wsadmin command, install the
application in install_root/installableApps/bpcivt.ear. After the enterprise
application is installed, it is in the state stopped, and any process and task
templates that it contains are in the state started. No process or task instances
can be created until the application is started.
2. Depending on where you configured Business Process Choreographer, make
sure that either:
v The application server is running.
v At least one member of the cluster is running.
3. Make sure that the database system, and messaging service are running.
4. Select the application BPCIVTApp and click Start to start the application.
5. Verify that the application works. Using a Web browser, open the following
page:
Chapter 4. Configuring Business Process Choreographer

267

http://app_server_host:port_no/bpcivt

Where app_server_host is the network name for the host of the application
server and port_no is the port number used by the virtual host to which you
mapped the IVT Web module when installing the file bpcivt.ear. The port
number depends on your system configuration. You should see a message
indicating success.
6. Optional: Stop and remove the bpcivt application.
7. If an error occurs, it can be caused by any of the following:
v If Business Process Choreographer cannot access the database, check that the
database system is running, that all database clients are correctly configured,
and that the data source is defined correctly. Make sure that the user ID and
password for the data source are valid.
v If Business Process Choreographer cannot read the input queues, check that
the messaging service is running, and make sure that the JMS provider and
JMS resources are defined correctly.
Results
The basic functionality of your Business Process Choreographer configuration
works.
What to do next
If you have configured other optional parts, such as the Business Process
Choreographer Observer, Business Process Choreographer Explorer, or a people
directory provider, they will need to be tested separately.

Understanding the startup behavior of Business Process


Choreographer
This topic explains why Business Process Choreographer is unavailable until all
enterprise applications are started.
When the Business Process Choreographer is started or restarted, no messages in
the internal queues are processed until all enterprise applications have started. It is
not possible to change this behavior. The time that the Business Flow Manager and
Human Task Manager are unavailable during a restart depends on how long it
takes until all enterprise applications are started. This behavior is necessary to
avoid navigating any processes with associated enterprise applications that are not
running.
Starting to process messages in the internal queue before all applications are
started would result in ClassNotFound exceptions.

Federating a stand-alone node that has Business Process


Choreographer configured
If your server is not running in development mode, you can federate a server that
is in a stand-alone profile to a new deployment manager cell.
Before you begin
The deployment manager is running, and you know its host name and port
number. Business Process Choreographer is configured on the server in a

268

Business Process Choreographer

stand-alone profile. The Business Process Choreographer database in the


stand-alone profile must be remotely accessible from the deployment manager cell.
For this reason, your server cannot be based on the sample Business Process
Choreographer configuration that uses the embedded Derby database. Also, the
database for the messaging engine database must be remotely accessible, that is, it
cannot be Derby Embedded and it cannot be FILESTORE.
About this task
You have one or more applications, which contain business processes or human
tasks, running on a stand-alone server, and you want to federate this server into a
network deployment environment.
Procedure
1. If the node includes a large number of applications, increase the timeout for the
administrative connector.
2. From the command line, run the addNode command with the -includeapps
and -includebuses options. For details about this command and possible errors
that can occur, refer to the WebSphere Application Server Network Deployment
information center, addNode command. For example, if the deployment
manager has a host name of dmgr_host and uses port dmgr_port, enter the
command:
addNode dmgr_host dmgr_port -includeapps -includebuses

For example, if the deployment manager has a host name of any.hostname.com


and uses port 9043, your profile name is ProcSvr07, your user ID is admin, and
your password is secret, enter the command:
addNode any.hostname.com 9043 -profileName ProcSvr07 -username admin
-password secret -includeapps -includebuses

If any of the prerequisites are not met, an error message is displayed.


Otherwise, the server is stopped and the server is federated into a new
deployment manager cell.
3. Start the server to activate the changes.
4. If you cannot access the business applications that are running on the server,
use the administrative console on the deployment manager to make sure that
the virtual host and alias definitions for the application server match the new
cell.
Results
Your applications are now running on the same server, but the server is now in a
cell that can be administered using the deployment manager.
What to do next
If required, you can promote the server to a cluster.

Chapter 4. Configuring Business Process Choreographer

269

270

Business Process Choreographer

Chapter 5. Removing the Business Process Choreographer


configuration
Use this task to remove the business process container, human task container,
Business Process Choreographer Explorer, Business Process Choreographer
Observer, and the associated resources.
Procedure
1. Ensure that all the stand-alone servers, the database, and the application server
(or at least one application server per cluster) are running.
2. For each enterprise application that contains human tasks or business
processes, stop all human task templates and all business process templates.
3. Uninstall all enterprise applications that contain human tasks or business
processes.
4. Perform one of the following actions:
v To remove the Business Process Choreographer configuration, Business
Process Choreographer Explorer, Business Process Choreographer Observer,
event collector, and the associated resources, perform Using a script to
remove the Business Process Choreographer configuration.
v If you want to reuse parts of the existing configuration, perform Using the
administrative console to remove the Business Process Choreographer
configuration on page 275.
Results
The Business Process Choreographer configuration has been removed.

Using a script to remove the Business Process Choreographer


configuration
Use this task to remove the Business Flow Manager, Human Task Manager,
Business Process Choreographer Explorer and Business Process Choreographer
Observer configuration, and the associated resources from a server or cluster.
Before you begin
Before you can remove the Business Process Choreographer configuration, you
must stop all process and task templates, delete all process and task instances, then
stop and remove all enterprise applications that contain business processes or
human tasks.
Procedure
1. Change to the Business Process Choreographer config directory:
On Windows platforms, enter the command:
cd install_root\ProcessChoreographer\config

On Linux, UNIX, and i5/OS platforms, enter:


cd install_root/ProcessChoreographer/config

2. Run the script bpeunconfig.jacl. In the following cases, also specify the
appropriate options:
Copyright IBM Corp. 2006, 2008

271

v For stand-alone servers, stop the application server and use the -conntype
NONE option. This step ensures that any databases are not locked and can be
removed automatically.
v In a network deployment environment, run the script, as follows:
If the deployment manager is not running, run the script on the
deployment manager, using the -conntype NONE option.
If the deployment manager is running, stop the application server from
which the configuration is to be removed, then run the script, omitting the
-conntype NONE option.
When the script is running on the application server node from which the
Business Process Choreographer configuration is to be removed, the script
can automatically delete any local Derby databases.
v If WebSphere administrative security is enabled, specify also the user ID and
password:
-user userID

-password password

v If you are not removing the configuring from the default profile, specify also
the profile name:
-profileName profileName
Option

Description

For a single server on Linux or UNIX

Enter the command:


install_root/bin/wsadmin.sh
-f bpeunconfig.jacl
-server Server -node Node
[-deleteDB deleteDatabase]
[-forcePredefTasks
forceUninstallPredefinedTasks]

For a single server on Windows

Enter the command:


install_root\bin\wsadmin.bat
-f bpeunconfig.jacl
-server Server -node Node
[-deleteDB deleteDatabase]
[-forcePredefTasks
forceUninstallPredefinedTasks]

For a single server on i5/OS

Enter the command:


install_root/bin/wsadmin
-f bpeunconfig.jacl
-server Server -node Node
[-deleteDB deleteDatabase]
[-forcePredefTasks
forceUninstallPredefinedTasks]

For a cluster on Linux or UNIX

Enter the command:


install_root/bin/wsadmin.sh
-f bpeunconfig.jacl
-cluster Cluster
[-forcePredefTasks
forceUninstallPredefinedTasks]

For a cluster on Windows

Enter the command:


install_root\bin\wsadmin.bat
-f bpeunconfig.jacl
-cluster Cluster
[-forcePredefTasks
forceUninstallPredefinedTasks]

272

Business Process Choreographer

Option

Description

For a cluster on i5/OS

Enter the command:


install_root/bin/wsadmin
-f bpeunconfig.jacl
-cluster Cluster
[-forcePredefTasks
forceUninstallPredefinedTasks]

Where:
userID The user ID.
password
The password for the user ID.
profileName
The name of the profile that is being configured. If you are configuring
the default profile, this option is optional.
Server The name of the application server. If only one server exists, this
parameter is optional.
Node The name of the node. This is optional. If the node is omitted, the local
node is used.
Cluster The name of the cluster.
deleteDatabase
A Boolean value that specifies whether to delete any Derby embedded
databases and FILESTORE directories:
yes
no
To use this option, the server must not be running. If you do not have
any non-Derby Embedded databases, and you use this option, after
running the script you can skip to step 4 on page 274.
forceUninstallPredefinedTasks
A Boolean value that specifies whether to force the removal of the
predefined Human Tasks enterprise application:
yes
no
If you select yes, the predefined Human Tasks application is removed from the
WebSphere configuration repository, but the corresponding entries remain in
the Business Process Choreographer database.
3. Optional: Delete the databases used by Business Process Choreographer.
For both the Business Process Choreographer database and the messaging
database the following apply:
v The bpeunconfig.jacl script lists the databases that were used by the
configuration that has been removed. The list of databases is also written to
the install_root/profiles/profileName/logs/bpeunconfig.log log file. You
can use this list to identify which databases you might want to delete
manually.
v When a Derby database is used for the Business Process Choreographer
database, the bpeunconfig.jacl script optionally removes the database,
unless it is locked by a running application server. If the database is locked,
stop the server, and use the -conntype NONE option.
v The bpeunconfig.jacl script optionally removes the database, unless it is
locked by a running application server. If the database is locked, stop the
server, and use the -conntype NONE option.

Chapter 5. Removing the Business Process Choreographer configuration

273

v When FILESTORE is used for the Business Process Choreographer messaging


engine message store, using the bpeunconfig.jacl scripts -deleteDB yes
option will also delete the associated directories.
v To remove the Business Process Choreographer Observer database, start the
tool to set up the event collector, as described in setupEventCollector tool
on page 258, and select the option Drop the database schema of the Event
Collector and Observer.
4. Optional: Check the bpeunconfig.log log file. It is located in the logs
subdirectory of the profile_root directory.
5. Optional: If you used WebSphere MQ, delete the queue manager used by
Business Process Choreographer.
6. Optional: Manually undo remaining settings that bpeunconfig.jacl does not
undo. The following settings are not undone by the bpeunconfig.jacl script
because it cannot determine whether the settings are still needed by other
components:
v Installing the BusinessCalendar system application
v Enabling the WorkAreaService
v
v
v
v
v
v

Enabling the ApplicationProfileService


Enabling the ObjectPoolService
Enabling the StartupBeansService
Enabling the CompensationService
Enabling the WorkareaPartitionService
Setting WebSphere variables

Results
The Business Process Choreographer applications and associated resources (such as
scheduler, data sources, listener ports, connection factories, queue destinations,
activation specs, work area partition, mail session, and authentication aliases) have
been removed.

Using tools to remove the Business Process Choreographer


Observer and event collector
Remove the Business Process Choreographer Observer and event collector
applications, and the associated resources from a server or cluster.
Procedure
1. If you configured Business Process Choreographer Observer, run the
setupObserver tool on page 261,, either specify the -remove option on the
command line, or select the Remove option on the initial menu.
2. If you configured Business Process Choreographer event collector application,
run the setupEventCollector tool on page 258, either specify the -remove
option on the command line, or select the Remove option on the initial menu.
3. Optional: If you installed the Java user-defined functions, remove them.
4. Optional: Delete the database.
Results
The Business Process Choreographer Observer and event collector applications
have been removed.

274

Business Process Choreographer

Using the administrative console to remove the Business Process


Choreographer configuration
Use this task to remove part or all of the Business Process Choreographer
configuration, including the Business Process Choreographer Explorer, Business
Process Choreographer Observer, and the associated resources.
Before you begin
Before you can remove the Business Process Choreographer configuration, you
must stop all process and task templates, delete all tasks and process instances,
then uninstall all enterprise applications that contain business processes or human
tasks.
Procedure
1. Uninstall the Business Process Choreographer enterprise applications.
a. Display the enterprise applications.
In the administrative console, select Applications Enterprise
Applications.
b. Identify the scope of the Business Process Choreographer installation.
Look for applications names that start with the following:
v BPEContainer_scope is the Business Flow Manager application.
v TaskContainer_scope is the Human Task Manager application.
v BPCExplorer_scope is the Business Process Choreographer Explorer
application.
v HTM_PredefinedTasks_scope and HTM_PredefinedTaskMsg_scope are for
the Business Process Choreographer Business Space.
Where the value of scope depends on your configuration:
v If Business Process Choreographer was configured on an application
server, scope has the value nodeName_serverName even if the server was
later promoted to a cluster.
v If Business Process Choreographer was configured on a cluster, scope has
the value clusterName.
c. Optional: If you configured Business Process Choreographer, uninstall the
Business Flow Manager and Human Task Manager applications. Select
BPEContainer_scope, and TaskContainer_scope, then click Uninstall OK
Save.
d. Optional: If you configured the Business Process Choreographer Explorer,
uninstall it.
v If you used the default context root, /bpc, select BPCExplorer_scope,
then click Uninstall OK Save.
v Otherwise, , select BPCExplorer_scope_context_root, then click
Uninstall OK Save.
Note: Uninstalling the Business Process Choreographer Observer and event
collector applications are described in step 10 on page 279.
2. Remove all or any of the following resources that you do not want to reuse:
a. Optional: Find the Business Process Choreographer data source (the
default name is BPEDataSourcedbType) and make a note of its name and its

Chapter 5. Removing the Business Process Choreographer configuration

275

associated authentication data alias (if any) and Java Naming and
Directory Interface (JNDI) name before removing it (the default name is
jdbc/BPEDB).
To find the data source:
1) Click Resources JDBC Data sources.
2) For Scope, select the server or cluster where Business Process
Choreographer was configured.
b. Optional: For a database other than a Derby database, remove the JDBC
provider of the data source identified in step 2 on page 275, unless it
contains further data sources that you still need. Click Resources JDBC
JDBC Providers, select the JDBC driver for your database and click
Delete.
Note: If the Business Process Choreographer configuration uses the
built-in default JDBC provider for the Derby Embedded database, this
JDBC provider cannot be deleted.
c. Optional: Remove the appropriate connection factories and queues.
v For default messaging, before you remove the connection factories, note
their associated authentication data aliases. Then remove the JMS
connection factories and JMS queues.
1) Click Resources JMS Connection factories. For Scope, select the
server or cluster where Business Process Choreographer was
configured. Then select the connection factory, and click Delete.
2) Click Resources JMS Queues. For Scope, select the server or
cluster where Business Process Choreographer was configured. Then
select the queues, and click Delete.
v For WebSphere MQ, remove the JMS queue connection factories and
JMS queues.
1) Click Resources JMS Queue connection factories. For Scope,
select the server or cluster where Business Process Choreographer
was configured. Then select the connection factory, and click Delete.
2) Click Resources JMS Queues. For Scope, select the server or
cluster where Business Process Choreographer was configured. Then
select the queues, and click Delete.
For the business process container the JNDI names are normally as
follows.Connection factories:
jms/BPECF
jms/BPECFC
jms/BFMJMSReplyCF
jms/BPEIntQueue
Queues:
jms/BPEIntQueue
jms/BPERetQueue
jms/BPEHldQueue
jms/BFMJMSAPIQueue
jms/BFMJMSCallbackQueue
jms/BFMJMSReplyQueue
For the human task container the JNDI names are normally as follows.
Connection factory:
jms/HTMCF
Queues:

276

Business Process Choreographer

jms/HTMIntQueue
jms/HTMHldQueue
d. Optional: If you are using WebSphere default messaging as the JMS
provider, remove the activation specifications.
1) Click Resources JMS Activation specifications. For Scope, select
the server or cluster where Business Process Choreographer was
configured.
2) Remove the following activation specifications:
BPEInternalActivationSpec
BFMJMSAS
HTMInternalActivationSpec
e. Optional: If you are using WebSphere MQ as the JMS provider, remove the
listener ports for the server.
1) Click Servers Application servers serverName.
2) Under Communications, click Messaging Message Listener Service
Listener Ports.
3) On the Application servers pane, remove the following listener ports:
BPEInternalListenerPort
BPEHoldListenerPort
HTMInternalListenerPort
If you configured Business Process Choreographer on a cluster, repeat this
step for each member of the cluster.
f. Optional: Delete the authentication data aliases.
1) Click Security Secure administration, applications, and
infrastructure then in the Authentication section, expand Java
Authentication and Authorization Service , click J2C authentication
data.
2) If the data source identified in step 2 on page 275 had an authentication
data alias, remove that alias. If you did not migrate your Business
Process Choreographer configuration from Version 6.0.x, the name
depends on the deployment target in the following manner:
v When Business Process Choreographer is configured on a server
named serverName, on a node named nodeName, the name is usually
BPCDB_nodeName.serverName_Auth_Alias.
v When Business Process Choreographer is configured on a cluster
named clusterName, the name is usually
BPCDB_clusterName_Auth_Alias
3) If any of the connection factories identified in step 2c on page 276 have
an authentication data alias, remove the alias with great care:
v If you did not migrate your Business Process Choreographer
configuration from Version 6.0.x, the name is BPC_Auth_Alias and it is
shared between all Business Process Choreographer configurations in
a network deployment environment.
Attention: Only remove this authentication alias if you are
removing the last Business Process Choreographer configuration,
otherwise the remaining Business Process Choreographer
configurations will stop working.
v

If you migrated your Business Process Choreographer configuration


from Version 6.0.x, the name is normally cellName/
BPEAuthDataAliasJMS_scope, where cellName is the name of the cell,

Chapter 5. Removing the Business Process Choreographer configuration

277

and scope identifies the deployment target. You can remove this
authentication alias without affecting other Business Process
Choreographer configurations.
g. Optional: Remove the scheduler configuration for the data source JNDI
name.
1) Click Resources Schedulers.
2) For Scope, select the server or cluster where Business Process
Choreographer was configured.
3) On the Schedulers pane, note the JNDI name of the work manager,
then select and delete the scheduler named BPEScheduler.
h. Optional: Remove the work manager.
1) Click Resources Asynchronous beans Work managers.
2) For Scope, select the server or cluster where Business Process
Choreographer was configured.
3) On the Work managers pane, select and delete the work manager
whose JNDI name you noted in step 2g.
4) Also delete the work manager with the JNDI name
wm/BPENavigationWorkManager.
i. Optional: Remove the work area partition.
1) Click Servers Application servers serverName.
2) Under the Container Settings section, expand Business Process
Services, click Work area partition service.
3) On the Application servers pane, select and delete the work area
partition BPECompensation.
If you configured Business Process Choreographer on a cluster, repeat this
step for each member of the cluster.
j. Optional: Remove the mail session.
1) Click Resources Mail Mail Providers.
2) For Scope, select the Cell=cellName, where cellName is the name of the
cell.
3) Click Built-in Mail Provider.
4) Under the Additional Properties section, select Mail sessions.
5) Select and delete HTMMailSession_scope, where scope is the scope
identified in step 1b on page 275
3. Optional: If you use WebSphere default messaging for Business Process
Choreographer, you can delete the bus member, bus, and data source:
a. Click Service integration Buses BPC.cellName.Bus, under the
Topology section, click Messaging engines.
b. Select the messaging engine:
v nodeName.serverName-BPC.cellName.Bus if you configured Business
Process Choreographer on a server.
v clusterName-BPC.cellName.Bus if you configured Business Process
Choreographer in a cluster.
Note: If you configured Business Process Choreographer to use a
remote messaging engine, nodeName.serverName or clusterName will not
match the name deployment target where you configured Business
Process Choreographer.
c. Under Additional Properties, select Message store.

278

Business Process Choreographer

4.

5.
6.
7.
8.
9.

v It the message store type is DATASTORE, note the JNDI name for the data
source. On a server the JNDI name of the data source is usually
jdbc/com.ibm.ws.sib/nodeName.serverName-BPC.cellName.Bus. On a
cluster the JNDI name of the data source is usually
jdbc/com.ibm.ws.sib/clusterName-BPC.cellName.Bus.
v If the message store type is FILESTORE, note the paths for Log, Permanent
store, and Temporary store.
d. Go to Service integration Buses BPC.cellName.Bus, under the
Topology section, click Bus members and remove the bus member
identified by one of the following names:
v nodeName:serverName if you configured Business Process Choreographer
on a server.
v clusterName if you configured Business Process Choreographer on a
cluster.
e. Optional: If you removed the last member of the bus BPC.cellName.Bus,
you can also remove the bus.
f. If the message store type that you noted in step 3c on page 278 was
DATASTORE, then click Resources JDBC Data Sources. The scope of the
messaging engine might not be the same as the deployment target where
you configured Business Process Choreographer. If necessary, trying
different scopes, look for the JNDI name that you noted in step 3c on page
278. If the data source is for a Derby database, note the file system path for
the database. If you configured Business Process Choreographer on a
cluster, repeat this step for each member of the cluster.
Delete the BPC_REMOTE_DESTINATION_LOCATION variable. Click Environment
WebSphere Variables, for Scope select the deployment target where Business
Process Choreographer was configured, then select and delete the variable
BPC_REMOTE_DESTINATION_LOCATION variable.
Click Save to save all your deletions in the master configuration.
Restart the application server or cluster.
Optional: Delete the Business Process Choreographer database.
Optional: If you are using WebSphere MQ, delete the queue manager used by
Business Process Choreographer.
If you use WebSphere default messaging for Business Process Choreographer,
delete the message store for the message engine; because it cannot be reused.
a. If the message store type that you noted in step 3c on page 278 was
FILESTORE, remove the directories that you noted for Log, Permanent store,
and Temporary store.
b. If the message store type that you noted in step 3c on page 278 was
DATASTORE, remove the database to which the data source pointed. If this
was a Derby data source, then delete the file system path that you noted
in step 3f. Usually, the Derby database location is the following:
v On Linux, UNIX, and i5/OS platforms:
profile_root/databases/com.ibm.ws.sib/
nodeName.serverName-BPC.cellName.Bus
v On Windows platforms:

profile_root\databases\com.ibm.ws.sib\
nodeName.serverName-BPC.cellName.Bus
10. Optional: If you configured the Business Process Choreographer Observer,
perform:
Chapter 5. Removing the Business Process Choreographer configuration

279

a. Using the administrative console to remove Business Process


Choreographer Observer on page 281 for each observer application
instance.
b. Using the administrative console to remove the Business Process
Choreographer event collector for each event collector application
instance.
Results
The Business Process Choreographer configuration has been removed.

Using the administrative console to remove the Business


Process Choreographer event collector
Use this task to remove the Business Process Choreographer event collector
configuration, and the associated resources that are required by the Business
Process Choreographer Observer.
Procedure
1. Display the enterprise applications.
In the administrative console, select Applications Enterprise Applications.
2. Uninstall the Business Process Choreographer event collector application.
Select the check box for BPCECollector_scope, click Uninstall OK. Where
scope identifies the server or cluster where the event collector was configured.
3. Delete the destination queues:
a. Click Service integration Buses CommonEventInfrastructure_Bus .
b. Under Destination resources, click Destinations.
c. Select the following destination queues:
v BPCCEIConsumerQueueDestination_scope
v BPCTransformerQueueDestination_scope
Where scope identifies the server or cluster where the event collector was
configured.
d. Click Delete.
4. Delete the JMS queue connection factory:
a. Click Resources JMS Queue connection factories.
b. For Scope, select the server or cluster where the event collector was
configured.
c. Select the check box for BPCCEIConsumerQueueConnectionFactory.
d. Click Delete.
5. Delete the JMS queues:
a. Click Resources JMS Queues.
b. Select the check boxes for the following queues:
v BPCCEIConsumerQueue_scope
v BPCTransformerQueue_scope
c. Click Delete.
6. Delete the JMS activation specifications:
a. Click Resources JMS Activation specifications.
b. Select the check boxes for the following activation specifications:
v BPCCEIConsumerActivationSpec

280

Business Process Choreographer

v BPCTransformerActivationSpec
c. Click Delete.
7. Delete the event profile group with server scope for BFMEvents:
a. Click Service integration Common Event Infrastructure Event service.
b. Under Additional Properties click Event services .
c. Click Default Common Event Infrastructure event server.
d. Under Additional Properties click Event groups .
e. Select the check box for BFMEvents.
f. Click Delete.
8. If you migrated your configuration from version 6.0.2, delete the
authentication data alias:
a. Click Security Secure administration, applications, and infrastructure
Authentication Java Authentication and Authorization Service J2C
authentication data.
b. select BPCEventCollectorJMSAuthenticationAlias_scope.
c. Click Delete.
9. Click Save to save your changes in the master configuration.
10. Drop the database, schema, and table space used by Business Process
Choreographer Observer by running the following scripts that on Windows
platforms are found in the directory install_root\dbscripts\
ProcessChoreographer\database_type , and on Linux, UNIX, and i5/OS
platforms in the directory install_root/dbscripts/ProcessChoreographer/
database_type:
v dropSchema_Observer.sql
v dropTablespace_Observer.sql
Results
The Business Process Choreographer event collector configuration has been
removed.

Using the administrative console to remove Business Process


Choreographer Observer
Use this task to remove Business Process Choreographer Observer configuration,
and the associated resources.
Procedure
1. Display the enterprise applications.
In the administrative console, select Applications Enterprise Applications.
2. Locate the Business Process Choreographer Observer instances.
Look for applications whose names start with BPCObserver_scope.
v If Business Process Choreographer Observer was installed on an application
server, scope has the value of nodeName_serverName.
v If Business Process Choreographer Observer was installed on a cluster, scope
has the value of clusterName.
Note: If the context root is not the default /bpcobserver, the application name
also has the context root appended to it, _contextRoot.

Chapter 5. Removing the Business Process Choreographer configuration

281

3. Uninstall the Business Process Choreographer Observer application. Select the


application instance that you want to deleted, then click Uninstall OK
Save.
Results
The Business Process Choreographer Observer configuration has been removed.

282

Business Process Choreographer

Part 3. Administering

Copyright IBM Corp. 2006, 2008

283

284

Business Process Choreographer

Chapter 6. Administering Business Process Choreographer


You can administer Business Process Choreographer using the administrative
console or using scripts.

Using the administrative console to administer Business Process


Choreographer
Describes the administrative actions that can be performed using the
administrative console.

Administering the compensation service for a server


Use the administrative console to start the compensation service automatically
when the application server starts, and to specify the location and maximum size
of the recovery log.
About this task
The compensation service must be started on an application server, when business
processes are run on that server. The compensation service is used to manage
updates that might be made in a number of transactions before the process
completes. When you set up a new application server, the compensation service is
enabled by default.
You can use the administrative console to view and change properties of the
compensation service for application servers.
Procedure
1. Display the administrative console.
2. In the navigation pane, click Servers Application servers server_name.
3. On the Configuration tab, under Container Settings, click Container Services
Compensation service. This action displays a panel with the compensation
service properties. Make sure that the Enable service at server startup check
box is selected. If you run your business processes on a cluster, enable the
compensation service for each server in the cluster.
4. Optional: If necessary, change the compensation service properties.
5. Click OK.
6. To save your configuration, click Save in the Messages box of the
administrative console window.

Querying and replaying failed messages, using the


administrative console
This describes how to check for and replay any messages for business processes or
human tasks that could not be processed.
About this task

IBM Corporation 2002, 2005

285

When a problem occurs while processing a message, it is moved to the retention


queue or hold queue. This task describes how to determine whether any failed
messages exist, and to send those messages to the internal queue again.
Procedure
1. To check how many messages are in the hold and retention queues:
a. Click Servers Application servers server_name, or Servers Clusters
cluster_name if Business Process Choreographer is configured on a cluster.
b. On the Configuration tab, under Business Integration, click Business
Process Choreographer. Choose one of the following options:
v For business processes, click Business Flow Manager.
v For human tasks, click Human Task Manager.
The number of messages in the hold queue and retention queue are
displayed on the Runtime tab under General Properties.
2. If either the hold queue or the retention queue contains messages, you can
move the messages to the internal work queue.
Click one of the following options:
v For business processes: Replay Hold Queue or Replay Retention Queue
v For human tasks: Replay Hold Queue
Note: When WebSphere administrative security is enabled, the replay buttons
are only visible to users who have operator authority.
Results
Business Process Choreographer tries to service all replayed messages again.
Related concepts
Recovery from infrastructure failures on page 32
A long-running process spans multiple transactions. If a transaction fails
because of an infrastructure failure, Business Flow Manager provides a facility
for automatically recovering from these failures.

Refreshing the failed message counts


Use the administrative console to refresh the count of failed messages for business
processes or human tasks.
About this task
The displayed number of messages in the hold queue and in the retention queue,
and the number of message exceptions, remain static until refreshed. This task
describes how to update and display the number of messages on those queues and
the number of message exceptions.
Procedure
1. Select the appropriate application server.
Click Servers Application servers server_name, or Servers Clusters
cluster_name if Business Process Choreographer is configured on a cluster.
2. Refresh the message counts.
a. On the Configuration tab, under Business Integration, click Business
Process Choreographer. Choose one of the following options:
v For business processes, click Business Flow Manager.

286

Business Process Choreographer

v For human tasks, click Human Task Manager.


b. On the Runtime tab, click Refresh Message Count.
Results
The following updated values are displayed under General Properties:
v For business processes: The number of messages in the hold queue and in the
retention queue
v For human tasks: The number of messages in the hold queue
v If any exceptions occurred while accessing the queues, the message text is
displayed in the Message exceptions field.
What to do next
On this page, you can also replay the messages in these queues.
Related concepts
Recovery from infrastructure failures on page 32
A long-running process spans multiple transactions. If a transaction fails
because of an infrastructure failure, Business Flow Manager provides a facility
for automatically recovering from these failures.

Refreshing people query results, using the administrative


console
The results of a people query are static. Use the administrative console to refresh
people queries.
About this task
Business Process Choreographer caches the results of people queries, which have
been evaluated against a people directory, such as a Lightweight Directory Access
Protocol (LDAP) server, in the runtime database. If the people directory changes,
you can force the people assignments to be evaluated again.
Procedure
To refresh the people queries:
1. Click Servers Application servers server_name, or Servers Clusters
cluster_name if Business Process Choreographer is configured on a cluster.
2. On the Configuration tab, under Business Integration, click Business Process
Choreographer Human Task Manager.
3. On the Runtime tab, click Refresh People Queries. All people queries are
refreshed.
Note: When WebSphere administrative security is enabled, the refresh button is
only visible to users who have operator authority.
Refreshing the people query results in this way can cause a high load on the
application and database. Consider using the alternative methods listed below.
Results
Related concepts
Managing people assignment criteria and people resolution results on page
90
Chapter 6. Administering Business Process Choreographer

287

A people assignment criteria that is associated with a task authorization role is


valid throughout the lifetime of a deployed task template or task instance.
Related tasks
Refreshing people query results, using administrative scripts on page 306
The results of a people query are static. Use the administrative scripts to refresh
people queries.
Refreshing people query results, using the refresh daemon on page 290
Use this method if you want to set up a regular and automatic refresh of all
expired people query results.

Enabling Common Base Events and the audit trail, using the
administrative console
Use this task to enable Business Process Choreographer events to be emitted to the
Common Event Infrastructure as Common Base Events, or stored in the audit trail,
or both.
About this task
You can change the state observers settings for the Business Flow Manager or the
Human Task Manager, permanently on the Configuration tab, or temporarily on
the Runtime tab. Any choices you make on these Configuration or Runtime tabs
affect all applications executing in the appropriate container. For changes to affect
both the Business Flow Manager and the Human Task Manager, you must change
the settings separately for them both.

Changing the configured logging infrastructure, using the


administrative console
Use this task to change the state observer logging for the audit log or common
event infrastructure logging for the configuration.
About this task
Choices made on the Configuration tab are activated the next time the server is
started. The chosen settings remain in effect whenever the server is started.
Make changes to the configuration, as follows:
Procedure
1. Display the Business Flow Manager or Human Task Manager pane.
a. Click Servers Application servers server_name, or Servers Cluster
cluster_name if Business Process Choreographer is configured on a cluster.
b. On the Configuration tab, under Business Integration, click Business
Process Choreographer. Choose one of the following options:
v For business processes, click Business Flow Manager.
v For human tasks, click Human Task Manager.
2. On the Configuration tab, in the General Properties section, select the logging
to be enabled. The state observers are independent of each other: you can
enable or disable either or both of them.
Enable Common Event Infrastructure logging
Select this check box to enable event emission that is based on the
Common Event Infrastructure.

288

Business Process Choreographer

Enable audit logging


Select this check box to store the audit log events in the audit trail
tables of the Business Process Choreographer database.
3. Accept the change.
a. Click OK.
b. In the Messages box, click Save.
Results
The state observers are set, as you required. The changes take place after server
restart.
What to do next
Restart the server, to effect the changes. If Business Process Choreographer is
configured on a cluster, restart the cluster.

Configuring the logging infrastructure for the session, using the


administrative console
Use this task to change the state observer logging for the audit log or common
event infrastructure logging for the session.
About this task
Choices made on the Runtime tab are effective immediately. The chosen settings
remain in effect until the next time the server is started.
Make changes to the session infrastructure, as follows:
Procedure
1. Display the Business Flow Manager or Human Task Manager pane.
a. Click Servers Application servers server_name, or Servers Clusters
cluster_name if Business Process Choreographer is configured on a cluster.
b. On the Configuration tab, under Business Integration, click Business
Process Choreographer. Choose one of the following options:
v For business processes, click Business Flow Manager.
v For human tasks, click Human Task Manager.
2. On the Runtime tab, in the General Properties section, select the logging to be
enabled. The state observers are independent of each other: you can enable or
disable either or both of them.
Enable Common Event Infrastructure logging
Select this check box to enable event emission that is based on the
Common Event Infrastructure.
Enable audit logging
Select this check box to store the audit log events in the audit trail
tables of the Business Process Choreographer database.
3. Click OK to accept the change.
Results
The state observers are set, as you required.

Chapter 6. Administering Business Process Choreographer

289

Refreshing people query results, using the refresh daemon


Use this method if you want to set up a regular and automatic refresh of all
expired people query results.
About this task
People queries are resolved by the specified people directory provider. The result is
stored in the Business Process Choreographer database. To optimize the
authorization performance, the retrieved query results are cached. The cache
content is checked for currency when the people query refresh daemon is invoked.
In order to keep people query results up to date, a daemon is provided that
refreshes expired people query results on a regular schedule. The daemon refreshes
all cached people query results that have expired.
Procedure
1. Open the custom properties page for the Human Task Manager:
a. Click Servers Application servers server_name, or Servers Clusters
cluster_name if Business Process Choreographer is configured on a cluster.
b. On the Configuration tab, under Business Integration, click Business
Process Choreographer Human Task Manager.
c. Choose one of the following options:
v To change the settings permanently, click the Configuration tab. The
changes are valid after the application server is restarted.
v To change the settings temporarily, click the Runtime tab. The changes
are valid immediately, but will be reset next time the application server
restarts.
2. In the field People query refresh schedule enter the schedule using the syntax
as supported by the WebSphere CRON calendar. This value determines when
the daemon will refresh any expired people query results. The default value is
0 0 1 * * ?, which causes a refresh every day at 1 am.
3. In the field Timeout for people query result enter a new value in seconds. This
value determines how long a people query result is considered to be valid.
After this time period, the people query result is considered to be no longer
valid, and the people query will be refreshed the next time that the daemon
runs. The default is one hour.
4. Click OK.
5. Save the changes. To make your changes that you performed on the
Configuration tab effective, restart the application server.
The new expiration time value applies only to new people queries, it does not
apply to existing people queries.
Related concepts
Managing people assignment criteria and people resolution results on page
90
A people assignment criteria that is associated with a task authorization role is
valid throughout the lifetime of a deployed task template or task instance.

Using scripts to administer Business Process Choreographer


Describes the administrative actions that can be performed using scripts.
Related reference

290

Business Process Choreographer

Using a script to enable logging for the Business Process Choreographer on


page 252
This describes how to use the setStateObserver.py script to enable or disable
Common Event Infrastructure (CEI) or audit events for Business Process
Choreographer.

Deleting audit log entries, using administrative scripts


Use the administrative scripts to delete some or all audit log entries for the
Business Flow Manager.
Before you begin
Before you begin this procedure, the following conditions must be met:
v The application server, through which audit log entries are to be deleted, must
be running. That is, the -conntype none option of wsadmin cannot be used,
because a server connection is required.
v If Business Process Choreographer is configured on a cluster, then at least one
cluster member must be running.
v When WebSphere administrative security is enabled, you must have operator
authority.
About this task
You can use the deleteAuditLog.py script to delete audit log entries for the
Business Flow Manager from the database.
Procedure
1. Change to the Business Process Choreographer subdirectory where the
administrative scripts are located.
On Windows platforms, enter:
cd install_root\ProcessChoreographer\admin

On Linux, UNIX, and i5/OS platforms, enter:


cd install_root/ProcessChoreographer/admin

2. Delete the entries in the audit log table.


On Windows platforms, enter one or more of the following commands. The
differences between the commands are emphasized:
install_root\bin\wsadmin -f deleteAuditLog.py
-server server_name
[-profileName profileName]
[options]
install_root\bin\wsadmin -f deleteAuditLog.py
-node node_name
-server server_name
[-profileName profileName]
[options]
install_root\bin\wsadmin -f deleteAuditLog.py
-cluster cluster_name
[-profileName profileName]
[options]

On Linux and UNIX platforms, enter one or more of the following commands.
The differences between the commands are emphasized:

Chapter 6. Administering Business Process Choreographer

291

install_root/bin/wsadmin.sh -f deleteAuditLog.py
-server server_name
[-profileName profileName]
[options]
install_root/bin/wsadmin.sh -f deleteAuditLog.py
-node node_name
-server server_name
[-profileName profileName]
[options]
install_root/bin/wsadmin.sh -f deleteAuditLog.py
-cluster cluster_name
[-profileName profileName]
[options]

On i5/OS platforms, enter one or more of the following commands. The


differences between the commands are emphasized:
install_root/bin/wsadmin -f deleteAuditLog.py
-server server_name
[-profileName profileName]
[options]
install_root/bin/wsadmin -f deleteAuditLog.py
-node node_name
-server server_name
[-profileName profileName]
[options]
install_root/bin/wsadmin -f deleteAuditLog.py
-cluster cluster_name
[-profileName profileName]
[options]

Where:
-cluster cluster_name
The name of the cluster. Required if the Business Flow Manager is
configured for a WebSphere cluster.
-node node_name
Optional when specifying the server name. This name identifies the node.
The default is the local node.
-server server_name
The name of the server. Required if the cluster name is not specified.
-profileName profileName
The name of a user-defined profile. Specify this option if you are not
working with the default profile.
The available options are:
-all
Deletes all the audit log entries in the database. The deletion is done in
multiple transactions. Each transaction deletes the number of entries
specified in the slice parameter, or the default number.
-time timestamp
Deletes all the audit log entries that are older than the time you specify for
timestamp. The time used is coordinated universal time (UTC). Its format
must be: YYYY-MM-DD[THH:MM:SS]. If you specify only the year, month, and
day, the hour, minutes, and seconds are set to 00:00:00.
The -time and -processtime options are mutually exclusive.

292

Business Process Choreographer

-processtime timestamp
Deletes all the audit log entries that belong to a process that finished before
the time you specify for timestamp. Use the same time format as for the
-time parameter.
The -time and -processtime options are mutually exclusive.
-slice size
Used with the -all parameter, size specifies the number of entries included
in each transaction. The optimum value depends on the available log size
for your database system. Higher values require fewer transactions but you
might exceed the database log space. Lower values might cause the script
to take longer to complete the deletion. The default size for the slice
parameter is 250.
Note: The jacl version of the cleanup unused people query script,
deleteAuditLog.jacl, is deprecated. It is available in the util subdirectory of
the ProcessChoreographer directory and it takes the same parameters as
described here, but the lang jython option must be omitted.

Deleting process templates that are unused


Use the administrative scripts to delete, from the Business Process Choreographer
database, business process templates that are no longer valid.
Before you begin
Before you begin this procedure, the application server on which templates are to
be deleted must be running. That is, the -conntype none option of wsadmin cannot
be used, because a server connection is required. No special authority is required
to run this command, even if WebSphere administrative security is enabled. If the
Business Process Choreographer is configured on a cluster, then at least one cluster
member must be running.
About this task
Use the deleteInvalidProcessTemplate.py script to remove, from the database, those
templates, and all objects that belong to them, that are not contained in any
corresponding valid application in the WebSphere configuration repository. This
situation can occur if an application installation was canceled or not stored in the
configuration repository by the user. These templates usually have no impact. They
are not shown in Business Process Choreographer Explorer.
There are rare situations in which these templates cannot be filtered. They must
then be removed from the database with the following scripts.
You cannot use the scripts to remove templates of valid applications from the
database. This condition is checked and a ConfigurationError exception is thrown
if the corresponding application is valid.
Procedure
1. Change to the Business Process Choreographer subdirectory where the
administrative scripts are located.
On Windows platforms, enter:
cd install_root\ProcessChoreographer\admin

On Linux, UNIX, and i5/OS platforms, enter:


Chapter 6. Administering Business Process Choreographer

293

cd install_root/ProcessChoreographer/admin

2. Delete, from the database, process templates that are no longer valid.
To delete, on Windows systems, a business process template that is no longer
valid, enter one of the following commands. The differences between the
commands are emphasized:
install_root\bin\wsadmin -f deleteInvalidProcessTemplate.py
-server server_name
-templateName templateName
-validFrom validFromString
[-profileName profileName]
install_root\bin\wsadmin -f deleteInvalidProcessTemplate.py
-server server_name
-node node_name
-templateName templateName
-validFrom validFromString
[-profileName profileName]
install_root\bin\wsadmin -f deleteInvalidProcessTemplate.py
-cluster cluster_name
-templateName templateName
-validFrom validFromString
[-profileName profileName]

To delete, on Linux and UNIX systems, a business process template that is no


longer valid, enter one of the following commands. The differences between the
commands are emphasized:
install_root/bin/wsadmin.sh -f deleteInvalidProcessTemplate.py
-server server_name
-templateName templateName
-validFrom validFromString
[-profileName profileName]
install_root/bin/wsadmin.sh -f deleteInvalidProcessTemplate.py
-server server_name
-node node_name
-templateName templateName
-validFrom validFromString
[-profileName profileName]
install_root/bin/wsadmin.sh -f deleteInvalidProcessTemplate.py
-cluster cluster_name
-templateName templateName
-validFrom validFromString
[-profileName profileName]

To delete, on i5/OS systems, a business process template that is no longer


valid, enter one of the following commands. The differences between the
commands are emphasized:
install_root/bin/wsadmin -f deleteInvalidProcessTemplate.py
-server server_name
-templateName templateName
-validFrom validFromString
[-profileName profileName]
install_root/bin/wsadmin -f deleteInvalidProcessTemplate.py
-server server_name
-node node_name
-templateName templateName
-validFrom validFromString
[-profileName profileName]
install_root/bin/wsadmin -f deleteInvalidProcessTemplate.py
-cluster cluster_name

294

Business Process Choreographer

-templateName templateName
-validFrom validFromString
[-profileName profileName]

Where:
-cluster cluster_name
The name of the cluster. Required if the Business Process Choreographer is
configured for a WebSphere cluster. You can specify the cluster name or the
server name and node name.
-node node_name
Optional when specifying the server name. This name identifies the node.
The default is the local node. You can specify the server name and node
name or the cluster name.
-server server_name
The name of the server. Required if the cluster name is not specified. You
can specify the server name and node name or the cluster name.
-templateName templateName
The name of the process template to be deleted.
-validFrom validFromString
The date from which the template is valid (in UTC) as displayed in the
administrative console. The string must have the following format:
yyyy-MM-ddThh:mm:ss (year, month, day, T, hours, minutes, seconds).
For example, 2005-01-31T13:40:50
-profileName profileName
The name of a user-defined profile. Specify this option if you are not
working with the default profile.
What to do next
Note: The jacl version of the cleanup unused processes script,
deleteInvalidProcessTemplate.jacl, is deprecated. It is available in the util
subdirectory of the ProcessChoreographer directory and it takes the same
parameters as described here, but the lang jython option must be omitted.

Deleting human task templates that are unused


Use the administrative scripts to delete, from the Business Process Choreographer
database, human task templates that are no longer valid.
Before you begin
Before you begin this procedure, the application server on which templates are to
be deleted must be running. That is, the -conntype none option of wsadmin cannot
be used, because a server connection is required. No special authority is required
to run this command, even if WebSphere administrative security is enabled. If the
Business Process Choreographer is configured on a cluster, then at least one cluster
member must be running.
About this task
Use the deleteInvalidTaskTemplate.py script to remove, from the database, those
templates, and all objects that belong to them, that are not contained in any
corresponding valid application in the WebSphere configuration repository. This
situation can occur if an application installation was canceled or not stored in the
Chapter 6. Administering Business Process Choreographer

295

configuration repository by the user. These templates usually have no impact. They
are not shown in Business Process Choreographer Explorer.
There are rare situations in which these templates cannot be filtered. They must
then be removed from the database with the following scripts.
You cannot use the scripts to remove templates of valid applications from the
database. This condition is checked and a ConfigurationError exception is thrown
if the corresponding application is valid.
Procedure
1. Change to the Business Process Choreographer subdirectory where the
administrative scripts are located.
On Windows platforms, enter:
cd install_root\ProcessChoreographer\admin

On Linux, UNIX, and i5/OS platforms, enter:


cd install_root/ProcessChoreographer/admin

2. Delete, from the database, human task templates that are no longer valid.
To delete, on Windows systems, a human task template that is no longer valid,
enter one of the following commands. The differences between the commands
are emphasized:
install_root\bin\wsadmin -f deleteInvalidTaskTemplate.py
-server server_name
-templateName templateName
-validFrom validFromString
-nameSpace nameSpace
[-profileName profileName]
install_root\bin\wsadmin -f deleteInvalidTaskTemplate.py
-server server_name
-node node_name
-templateName templateName
-validFrom validFromString
-nameSpace nameSpace
[-profileName profileName]
install_root\bin\wsadmin -f deleteInvalidTaskTemplate.py
-cluster cluster_name
-templateName templateName
-validFrom validFromString
-nameSpace nameSpace
[-profileName profileName]

To delete, on UNIX and Linux systems, a human task template that is no longer
valid, enter one of the following commands. The differences between the
commands are emphasized:
install_root/bin/wsadmin.sh -f deleteInvalidTaskTemplate.py
-server server_name
-templateName templateName
-validFrom validFromString
-nameSpace nameSpace
[-profileName profileName]
install_root/bin/wsadmin.sh -f deleteInvalidTaskTemplate.py
-server server_name
-node node_name
-templateName templateName
-validFrom validFromString
-nameSpace nameSpace
[-profileName profileName]

296

Business Process Choreographer

install_root/bin/wsadmin.sh -f deleteInvalidTaskTemplate.py
-cluster cluster_name
-templateName templateName
-validFrom validFromString
-nameSpace nameSpace
[-profileName profileName]

To delete, on i5/OS systems, a human task template that is no longer valid,


enter one of the following commands. The differences between the commands
are emphasized:
install_root/bin/wsadmin -f deleteInvalidTaskTemplate.py
-server server_name
-templateName templateName
-validFrom validFromString
-nameSpace nameSpace
[-profileName profileName]
install_root/bin/wsadmin -f deleteInvalidTaskTemplate.py
-server server_name
-node node_name
-templateName templateName
-validFrom validFromString
-nameSpace nameSpace
[-profileName profileName]
install_root/bin/wsadmin -f deleteInvalidTaskTemplate.py
-cluster cluster_name
-templateName templateName
-validFrom validFromString
-nameSpace nameSpace
[-profileName profileName]

Where:
-cluster cluster_name
The name of the cluster. Required if the Business Process Choreographer is
configured for a WebSphere cluster. You can specify the cluster name or the
server name and node name.
-node node_name
Optional when specifying the server name. This name identifies the node.
The default is the local node. You can specify the server name and node
name or the cluster name.
-server server_name
The name of the server. Required if the cluster name is not specified. You
can specify the server name and node name or the cluster name.
-templateName templateName
The name of the task template to be deleted.
-validFrom validFromString
The date from which the template is valid (in UTC) as displayed in the
administrative console. The string must have the following format:
yyyy-MM-ddThh:mm:ss (year, month, day, T, hours, minutes, seconds).
For example, 2005-01-31T13:40:50
-nameSpace nameSpace
The target namespace of the task template.
-profileName profileName
The name of a user-defined profile. Specify this option if you are not
working with the default profile.

Chapter 6. Administering Business Process Choreographer

297

What to do next
Note: The jacl version of the cleanup unused people query script,
deleteInvalidTaskTemplate.jacl, is deprecated. It is available in the util
subdirectory of the ProcessChoreographer directory and it takes the same
parameters as described here, but the lang jython option must be omitted.

Deleting completed process instances


Use an administrative script to selectively delete from the Business Process
Choreographer database any top-level process instances that have reached an end
state of finished, terminated, or failed.
Before you begin
Before you begin this procedure, the application server on which process instances
are to be deleted must be running. That is, the -conntype none option of wsadmin
cannot be used, because a server connection is required. No special authority is
required to run this command, even if WebSphere administrative security is
enabled. If Business Process Choreographer is configured on a cluster, then at least
one cluster member must be running.
About this task
A top-level process instance is considered completed if it is in one of the following
end states: finished, terminated, or failed. You specify criteria to selectively delete
top-level process instances and all their associated data (such as activity instances,
child process instances, and inline task instances) from the database.
Procedure
1. Change to the Business Process Choreographer subdirectory where the
administrative scripts are located.
On Windows platforms, enter:
cd install_root\ProcessChoreographer\admin

On Linux, UNIX, and i5/OS platforms, enter:


cd install_root/ProcessChoreographer/admin

2. Delete process instances from the database.


On Windows systems, enter the following command:
install_root\bin\wsadmin f deleteCompletedProcessInstances.py
[([-node nodeName] -server server_name) | (-cluster cluster_name)]
(-all | -finished | -terminated | -failed )
[-templateName templateName [-validFrom timestamp]]
[-startedBy userID ]
[-completedBefore timestamp]
[-profileName profileName]

On Linux and UNIX systems, enter the following command:


install_root/bin/wsadmin.sh f deleteCompletedProcessInstances.py
[([-node nodeName] -server server_name) | (-cluster cluster_name)]
(-all | -finished | -terminated | -failed )
[-templateName templateName [-validFrom timestamp]]
[-startedBy userID ]
[-completedBefore timestamp]
[-profileName profileName]

On i5/OS systems, enter the following command:

298

Business Process Choreographer

install_root/bin/wsadmin f deleteCompletedProcessInstances.py
[([-node nodeName] -server server_name) | (-cluster cluster_name)]
(-all | -finished | -terminated | -failed )
[-templateName templateName [-validFrom timestamp]]
[-startedBy userID ]
[-completedBefore timestamp]
[-profileName profileName]

Where:
-node nodeName
Optional when specifying the server name. This name identifies the node.
The default is the local node. You can specify the server name and node
name or the cluster name.
-server server_name
The name of the server. Required if the cluster name is not specified. You
can specify the server name and node name or the cluster name.
-cluster cluster_name
The name of the cluster. Required if the Business Process Choreographer is
configured for a WebSphere cluster. You can specify the cluster name or the
server name and node name.
-all|-finished|-terminated|-failed
Specifies which process instances are to be deleted according to their state.
-templateName templateName
Optionally, specifies the name of the process template to be deleted. If this
option is specified, you can also use the validFrom parameter.
-validFrom timestamp
The date from which the template is valid (in UTC) as displayed in the
administrative console. This option can only be used with the
templateName option. The timestamp string has the following format:
yyyy-MM-ddThh:mm:ss (year, month, day, T, hours, minutes, seconds).
For example, 2006-11-20T12:00:00.
-startedBy userID
Optionally, only deletes completed process instances that were started by
the given User ID.
-completedBefore timestamp
Optionally, deletes completed process instances that completed before the
given time. The timestamp string has the following format:
yyyy-MM-dd[Thh:mm:ss] (year, month, day, T, hours, minutes, seconds).
For example, 2006-07-20T12:00:00. If you specify only the year, month, and
day, the hour, minutes, and seconds are set to 00:00:00.
-profileName profileName
The name of a user-defined profile. Specify this option if you are not
working with the default profile.
For example, to delete all of the process instances running on node myNode in
server myServer that are in the state finished, and were started by the user
Antje, run the following command:
wsadmin f deleteCompletedProcessInstances.py
-node myNode -server myServer
-finished
-startedBy Antje

Results
Chapter 6. Administering Business Process Choreographer

299

The completed process instances have been deleted from the database.

Deleting data from the observer database


Use an administrative script to selectively delete from the Business Process
Choreographer Observer database, all of the data for process instances that match
specified conditions.