V5.4.0.

cover

Front cover

IBM FileNet Business

Process Manager 5.0: Java
API Programming

(Course code F156)

Student Notebook
ERC 1.0
Student Notebook

Trademarks
IBM® and the IBM logo are registered trademarks of International Business Machines
Corporation.
The following are trademarks of International Business Machines Corporation, registered in
many jurisdictions worldwide:
Cognos® DB2® FileNet®
WebSphere®
Java and all Java-based trademarks and logos are trademarks of Sun Microsystems, Inc.
in the United States, other countries, or both.
Linux® is a registered trademark of Linus Torvalds in the United States, other countries, or
both.
Microsoft and Windows are trademarks of Microsoft Corporation in the United States, other
countries, or both.
UNIX® is a registered trademark of The Open Group in the United States and other
countries.
Other product and service names might be trademarks of IBM or other companies.

August 2011 edition

The information contained in this document has not been submitted to any formal IBM test and is distributed on an “as is” basis without
any warranty either express or implied. The use of this information or the implementation of any of these techniques is a customer
responsibility and depends on the customer’s ability to evaluate and integrate them into the customer’s operational environment. While
each item may have been reviewed by IBM for accuracy in a specific situation, there is no guarantee that the same or similar results will
result elsewhere. Customers attempting to adapt these techniques to their own environments do so at their own risk.

This information contains examples of data and reports used in daily business operations. To illustrate them as completely as possible,
the examples include the names of individuals, companies, brands, and products. All of these names are fictitious, and any similarity to
the names and addresses used by a real business enterprise is entirely coincidental.

© Copyright International Business Machines Corporation 2011.

This document may not be reproduced in whole or in part without the prior written permission of IBM.
Note to U.S. Government Users — Documentation related to restricted rights — Use, duplication or disclosure is subject to restrictions
set forth in GSA ADP Schedule Contract with IBM Corp.
V5.4.0.3
Student Notebook

TOC Contents
Trademarks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xv

Course description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xvii

Unit 1. IBM FileNet Business Process Manager Introduction . . . . . . . . . . . . . . . . . . 1-1

Unit lessons . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-2
Lesson 1.1. Workflow fundamentals . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-3
Workflow fundamentals . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-4
Activities that you need to complete . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-5
Process automation with IBM FileNet BPM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-6
Workflows and workflow definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-7
Process Designer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-9
Workflow maps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-11
Step and workflow properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-13
Work items . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-15
Queues . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-17
Workflow rosters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-19
Workflow history and statistics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-21
Demonstrations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-23
Activities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-25
Lesson 1.2. Workflow processing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-27
Workflow processing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-28
Activities that you need to complete . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-29
Workflow processing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-30
How workflows are launched . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-31
Inboxes, work queues, and step processors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-33
Process tracking . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-35
Search for work in Process Administrator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-36
Search targets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-38
Milestones, deadlines, and timers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-39
Process connectivity features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-40
Activities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-41
Lesson 1.3. IBM FileNet BPM architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-43
IBM FileNet BPM architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-44
Activities that you need to complete . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-45
Principal components of IBM FileNet BPM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-46
Other FileNet BPM software components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-47
Process Service on the Process Engine . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-48
Workflow database . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-50
Component Integrator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-51
Process Task Manager (PTM) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-53
BPM tools (Java applets) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-55
Process Engine farming . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-56
Process Engine multitenancy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-58

©Copyright IBM Corp. 2011 Contents iii

Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
Student Notebook

Architecture overview of IBM FileNet BPM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1-60

Activities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1-62

Unit 2. Process Engine Java API Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-1

Unit lessons . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-2
Lesson 2.1. Process Engine Java API concepts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-3
Lesson: Process Engine Java API concepts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-4
Activities that you need to complete . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-5
Process API package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-6
Process API naming conventions - objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-7
Process API naming conventions - methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-8
Primary API classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-10
Process development environment and samples . . . . . . . . . . . . . . . . . . . . . . . . . .2-12
Required Java Archive (JAR) files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-13
Configuring the Java runtime environment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-14
Activities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-16
Lesson 2.2. Process Engine objects. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-17
Lesson: Process Engine objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-18
Activities that you need to complete . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-19
Runtime objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-20
Database objects - typical isolated region . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-21
Work elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-23
Work object access . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-24
Work element access . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-25
Work class objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-27
Administration and configuration objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-29
Security objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-30
Workflow definition objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-31
Using Eclipse IDE for writing your code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-32
Demonstrations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-33
Activities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-34

Unit 3. Log On to the Process Engine. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-1

Unit lessons . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-2
Lesson 3.1. Create a Process Engine session . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-3
Lesson: Create a Process Engine session . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-4
Activities that you need to complete . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-5
Connection points . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-6
Connection point function and usage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-7
Setting the Content Engine URI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-9
System dependency for the Process Engine . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-10
Authenticating the PE Java API client using CE . . . . . . . . . . . . . . . . . . . . . . . . . . .3-11
VWSession object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-13
VWSession constructor options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-14
Steps to log on to and log off from the Process Engine . . . . . . . . . . . . . . . . . . . . .3-15
VWSession constructor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-16
vwSession.logon(...) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-17
vwSession.logoff() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-18

iv IBM FileNet BPM 5.0: Java API Programming ©Copyright IBM Corp. 2011
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
V5.4.0.3
Student Notebook

TOC Sample code to log on to and log off from PE . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-19

Sample code to log on to the Process Engine (JSP) . . . . . . . . . . . . . . . . . . . . . . 3-20
Demonstrations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-21
Activities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-22
Lesson 3.2. Handle exceptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-23
Lesson: Handle exceptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-24
Activities that you need to complete . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-25
VWException object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-26
Steps to handle a VWException . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-28
vwException.getKey() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-29
vwException.getCauseClassName() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-30
vwException.getCauseDescription() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-31
vwException.getMessage() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-32
Sample code to handle an exception . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-33
Demonstrations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-34
Activities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-35
Lesson 3.3. Retrieve user and group information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-37
Lesson: Retrieve user and group information . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-38
Activities that you need to complete . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-39
Steps to get current user information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-40
vwSession.fetchCurrentUserInfo() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-41
vwUserInfo.getName() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-42
vwUserInfo.getEMailAddress() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-43
vwUserInfo.getProxyUserName() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-44
Sample code to get current user information . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-45
Steps to get the LDAP users and groups . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-46
vwSession.findUsers(...) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-47
vwSession.convertUserNameToId(...) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-49
vwSession.findGroups(...) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-50
Sample code to get the current Process Engine user . . . . . . . . . . . . . . . . . . . . . . 3-51
Sample code to get the Process Engine users . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-52
Sample code to get the Process Engine groups . . . . . . . . . . . . . . . . . . . . . . . . . . 3-53
Demonstrations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-54
Activities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-55

Unit 4. Create Work . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-1

Unit lessons . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-2
Lesson 4.1. Retrieve and launch a workflow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-3
Lesson: Retrieve and launch a workflow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-4
Activities that you need to complete . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-5
Steps to retrieve and launch a workflow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-6
vwSession.fetchWorkClassNames(...) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-7
vwSession.createWorkflow(...) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-8
vwStepElement.doDispatch() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-9
Sample code to retrieve and launch a workflow . . . . . . . . . . . . . . . . . . . . . . . . . . 4-10
Demonstrations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-11
Activities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-12
Lesson 4.2. Retrieve parameter values for a step element . . . . . . . . . . . . . . . . . . . . . . 4-13

©Copyright IBM Corp. 2011 Contents v

Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
Student Notebook

Lesson: Retrieve parameter values for a step element . . . . . . . . . . . . . . . . . . . . .4-14

Activities that you need to complete . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-15
Steps to retrieve parameters values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-16
vwStepElement.getParameters(...) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-17
vwStepElement.getStepName() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-19
vwParameter. getFieldType() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-20
vwParameter.getMode() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-21
VWFieldType.getLocalizedString(...) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-22
VWModeType.getLocalizedString() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-23
vwParameter.getStringValue() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-24
vwStepElement.getStepResponses() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-25
Sample code to retrieve step element fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-26
Sample code to retrieve parameter values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-27
Demonstrations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-28
Activities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-29
Lesson 4.3. Set parameter values for a step element . . . . . . . . . . . . . . . . . . . . . . . . . .4-31
Lesson: Set parameter values for a step element . . . . . . . . . . . . . . . . . . . . . . . . .4-32
Activities that you need to complete . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-33
VWParticipant class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-34
VWAttachment class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-35
Steps to set parameters values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-36
Steps to set VWParticipant value . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-37
Steps to set VWAttachment value (1) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-38
Steps to set VWAttachment value (2) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-39
vwParameter.isArray() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-40
vwStepElement.setParameterValue(...) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-41
vwParticipant.setParticipantName(...) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-42
vwStepElement.setSelectedResponse(...) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-43
vwAttachment.setAttachmentName(...) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-44
vwAttachment.setType(...) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-45
vwAttachment.setLibraryType(...) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-46
vwAttachment.setLibraryName(...) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-47
vwAttachment.setId(...) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-48
vwAttachment.setVersion(...) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-49
Sample code to set parameter values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-50
Sample code to set VWParticipants value . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-51
Sample code to set VWAttachment value . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-52
Sample code to set response parameter value . . . . . . . . . . . . . . . . . . . . . . . . . . .4-53
Demonstrations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-54
Activities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-55
Lesson 4.4. Automatically launch a workflow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-57
Lesson: Automatically launch a workflow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-58
Activities that you need to complete . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-59
Workflow subscription . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-60
Steps to create a workflow subscription . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-61
Select the target and define the conditions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-62
Map workflow data fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-63
Entry templates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-64

vi IBM FileNet BPM 5.0: Java API Programming ©Copyright IBM Corp. 2011
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
V5.4.0.3
Student Notebook

TOC Entry Template Designer wizard . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-65

Steps to use a document entry template . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-66
Demonstrations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-67
Activities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-68

Unit 5. Find Work . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-1

Unit lessons . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-2
Lesson 5.1. Query a roster . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-3
Lesson: Query a roster . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-4
Activities that you need to complete . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-5
Workflow rosters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-6
Work objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-7
Steps to retrieve roster work items (1) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-9
Steps to retrieve roster work items (2) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-10
vwSession.getRoster(...) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-11
vwRoster.fetchCount() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-12
vwRoster.createQuery(...) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-13
vwRosterQuery.next() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-15
vwRosterElement.getWorkflowNumber() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-16
vwRosterElement.getWorkObjectNumber() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-17
vwRosterElement.getFieldValue(...) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-18
Sample code to retrieve roster items . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-19
Sample code to display roster work items . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-20
Demonstrations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-21
Activities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-23
Lesson 5.2. Query a queue . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-25
Lesson: Query a queue . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-26
Activities that you need to complete . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-27
Steps to retrieve queue names in a given region . . . . . . . . . . . . . . . . . . . . . . . . . 5-28
Steps to retrieve queue elements (1) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-29
Steps to retrieve queue elements (2) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-30
Queue methods similar to roster methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-31
vwSession.fetchQueueNames() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-32
vwQueue.getIsConnectorQueue() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-33
vwQueue.fetchCount() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-34
vwQueue.createQuery(...) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-35
vwQueueQuery.fetchCount() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-37
vwQueueElement.getWorkflowName() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-38
Sample code to retrieve queues . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-39
Sample code to query a queue . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-40
Sample code to display queue items . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-41
Demonstrations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-42
Activities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-43
Lesson 5.3. Query an event log. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-45
Lesson: Query an event log . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-46
Activities that you need to complete . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-47
Steps to retrieve log elements (1) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-48
Steps to retrieve log elements (2) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-49

©Copyright IBM Corp. 2011 Contents vii

Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
Student Notebook

vwSession.fetchEventLog(...) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5-50
vwLog.startQuery(...) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5-51
vwLogQuery.fetchCount() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5-52
vwLogElement.getEventType() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5-53
vwLogElement.getFieldValue(...) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5-55
vwLoggingOptionType.getLocalizedString(...) . . . . . . . . . . . . . . . . . . . . . . . . . . . .5-56
Sample code to query the event log . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5-57
Sample code to retrieve event log elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5-58
Demonstrations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5-59
Activities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5-60

Unit 6. Process Work . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .6-1

Unit lessons . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .6-2
Lesson 6.1. Retrieve a step element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .6-3
Lesson: Retrieve a step element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .6-4
Activities that you need to complete . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .6-5
Steps to retrieve step element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .6-6
Inbox and Inbox(0) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .6-7
vwQueue.createQuery(...) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .6-8
Sample code to retrieve a step element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .6-9
Demonstrations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .6-10
Activities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .6-11
Lesson 6.2. Retrieve parameter values for a step element . . . . . . . . . . . . . . . . . . . . . .6-13
Lesson: Retrieve parameter values for a step element . . . . . . . . . . . . . . . . . . . . .6-14
Activities that you need to complete . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .6-15
Steps to retrieve queue elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .6-16
vwStepElement.getParameters(...) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .6-17
vwStepElement.getStepName() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .6-19
vwParameter.getMode() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .6-20
VWFieldType.getLocalizedString(...) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .6-21
VWModeType.getLocalizedString() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .6-22
vwStepElement.getStepResponses() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .6-23
Sample code to retrieve parameter values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .6-24
Sample code to retrieve step element responses . . . . . . . . . . . . . . . . . . . . . . . . . .6-25
Activities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .6-26
Lesson 6.3. Set parameter values for a step element . . . . . . . . . . . . . . . . . . . . . . . . . .6-27
Lesson: Set parameter values for a step element . . . . . . . . . . . . . . . . . . . . . . . . .6-28
Activities that you need to complete . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .6-29
Steps to retrieve queue elements (1) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .6-30
Steps to retrieve queue elements (2) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .6-31
Steps to set VWParticipant . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .6-32
Steps to set VWAttachment (1) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .6-33
Steps to set VWAttachment (2) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .6-34
vwStepElement.doLock(...) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .6-35
vwParameter.isArray() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .6-36
vwStepElement.setParameterValue(...) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .6-37
vwParticipant.setParticipantName(...) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .6-38
vwAttachment.setType(...) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .6-39

viii IBM FileNet BPM 5.0: Java API Programming ©Copyright IBM Corp. 2011
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
V5.4.0.3
Student Notebook

TOC vwStepElement.setSelectedResponse(...) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-41

Sample code to set parameters values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-42
Sample code to set VWParticipant . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-43
Sample code to set VWAttachment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-44
Sample code to set response parameter value . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-45
Activities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-46
Lesson 6.4. Complete a work item . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-47
Lesson: Complete a work item . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-48
Activities that you need to complete . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-49
Steps to get processing options of a step element . . . . . . . . . . . . . . . . . . . . . . . . 6-50
vwStepElement.getCanReassign() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-51
vwStepElement.doReassign(...) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-52
vwStepElement.getCanReturnToSource() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-53
vwStepElement.doReturnToSource() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-54
Sample code to get step element processing options . . . . . . . . . . . . . . . . . . . . . . 6-55
Steps to complete a work item . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-56
vwStepElement.doSave(...) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-57
vwStepElement.doAbort() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-58
vwStepElement.doDispatch() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-59
Sample code to complete a work item . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-60
Demonstrations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-61
Activities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-62

Unit 7. Retrieve Work Status . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-1

Unit lessons . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-2
Lesson 7.1. Retrieve workflow history . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-3
Lesson: Retrieve workflow history . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-4
Activities that you need to complete . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-5
Steps to retrieve workflow history (Flow) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-6
Steps to retrieve workflow history (1) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-7
Steps to retrieve workflow history (2) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-8
Workflow history information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-9
Java API methods calling sequence . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-10
vwWorkObject.fetchProcess() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-11
vwSession.fetchProcess(...) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-12
vwProcess.fetchWorkflowDefinition(...) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-13
vwWorkflowDefinition.getMaps() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-14
vwMapDefinition.getMapId() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-15
vwWorkflowHistory.next() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-16
vwStepHistory.next() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-17
vwStepOccurrenceHistory.next() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-18
vwStepWorkObjectHistory.next() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-19
vwParticipantHistory.getUserName() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-20
Sample code to retrieve workflow history (1) . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-21
Sample code to retrieve workflow history (2) . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-22
Sample code to retrieve workflow history (3) . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-23
Sample code to retrieve workflow history (4) . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-24
Demonstrations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-25

©Copyright IBM Corp. 2011 Contents ix

Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
Student Notebook

Activities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .7-27
Lesson 7.2. Retrieve milestones. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .7-29
Lesson: Retrieve milestones . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .7-30
Activities that you need to complete . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .7-31
Steps to display milestone history information . . . . . . . . . . . . . . . . . . . . . . . . . . . .7-32
vwProcess.fetchReachedWorkflowMilestones(...) . . . . . . . . . . . . . . . . . . . . . . . . .7-33
vwWorkflowMilestones.next() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .7-34
vwMilestoneElement.getMessage() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .7-35
Sample code to retrieve milestone information . . . . . . . . . . . . . . . . . . . . . . . . . . . .7-36
Demonstrations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .7-37
Activities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .7-38

Unit 8. Work with Component Integrator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .8-1

Unit lessons . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .8-2
Lesson 8.1. Component integration concepts. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .8-3
Lesson: Component integration concepts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .8-4
Activities that you need to complete . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .8-5
About Component Integrator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .8-6
Purposes for component integration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .8-8
Components Behavior . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .8-9
Component Integrator architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .8-11
Components and the isolated region . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .8-12
Types of components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .8-14
Content Extended operations (CE_Operations) . . . . . . . . . . . . . . . . . . . . . . . . . . .8-16
Steps to use CE_Operations in a workflow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .8-17
Demonstrations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .8-18
Activities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .8-19
Lesson 8.2. Create and configure a Component Manager . . . . . . . . . . . . . . . . . . . . . . .8-21
Lesson: Create and configure a Component Manager . . . . . . . . . . . . . . . . . . . . . .8-22
Activities that you need to complete . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .8-23
About Component Manager . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .8-24
Reasons for multiple Component Managers . . . . . . . . . . . . . . . . . . . . . . . . . . . . .8-25
How to create a new Component Manager . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .8-26
Set a connection point for a Component Manager . . . . . . . . . . . . . . . . . . . . . . . . .8-27
Set component queues . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .8-28
Set Component Manager library paths . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .8-29
Start and stop components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .8-31
Demonstrations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .8-32
Activities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .8-34
Lesson 8.3. Configure a Java component queue . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .8-35
Lesson: Configure a Java component queue . . . . . . . . . . . . . . . . . . . . . . . . . . . . .8-36
Activities that you need to complete . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .8-37
About Java components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .8-38
Developing Java components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .8-39
JAAS-based authentication model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .8-40
What is a LoginContext? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .8-41
CELoginModule . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .8-42
CELogin context . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .8-43

x IBM FileNet BPM 5.0: Java API Programming ©Copyright IBM Corp. 2011
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
V5.4.0.3
Student Notebook

TOC Steps to create a LoginContext . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-44

Sample code to retrieve VWSession . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-45
Sample code to access Content Engine objects . . . . . . . . . . . . . . . . . . . . . . . . . . 8-46
Deploying Java Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-47
How to create a Java component queue . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-48
Configure the Java component adaptor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-49
Import component queue operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-50
Demonstrations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-52
Activities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-54
Lesson 8.4. Configure component queues for JMS . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-55
Appendix: Configure component queues for JMS . . . . . . . . . . . . . . . . . . . . . . . . . 8-56
JMS component adaptor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-57
How to create a JMS component queue . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-59
Configure general queue properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-60
Configure the JMS component . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-61
Set adaptor properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-62
Assign JAAS credentials . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-63
Define component queue operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-64
Define component queue operations window . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-65
Confirm access to JMS queue . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-66

Unit 9. Use Roles and Workbaskets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-1

Unit lessons . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-2
Lesson 9.1. Retrieve application spaces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-3
Lesson: Retrieve application spaces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-4
Activities that you need to complete . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-5
Application spaces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-6
Application space and roles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-7
Create an application space . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-8
Configure roles for an application space . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-10
Steps to retrieve application spaces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-11
vwSession.fetchSystemConfiguration() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-12
vwSystemConfiguration.getApplicationSpaceDefinitions() . . . . . . . . . . . . . . . . . . 9-13
vwApplicationSpaceDefinition.getName() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-14
Sample code to get application spaces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-15
Demonstrations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-16
Activities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-17
Lesson 9.2. Retrieve roles. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-19
Lesson: Retrieve roles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-20
Activities that you need to complete . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-21
Roles, in-baskets, filters, and queues relationship . . . . . . . . . . . . . . . . . . . . . . . . 9-22
Creating roles at design time . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-23
How roles work at run time . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-25
Assign LDAP users and groups . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-26
Associate role with in-baskets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-27
VWRole object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-28
Steps to retrieve all roles in an application space . . . . . . . . . . . . . . . . . . . . . . . . . 9-30
Steps to retrieve roles for a given user . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-31

©Copyright IBM Corp. 2011 Contents xi

Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
Student Notebook

vwApplicationSpaceDefinition.getRoleDefinitions() . . . . . . . . . . . . . . . . . . . . . . . .9-32
vwApplicationSpaceDefinition.getRoleDefinition() . . . . . . . . . . . . . . . . . . . . . . . . .9-33
vwSesssion.fetchMyRoles(...) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .9-34
vwSesssion.fetchMyRole(...) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .9-35
vwRole.getName() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .9-36
vwRole.getAuthoredName() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .9-37
Sample code to retrieve all roles in an application space . . . . . . . . . . . . . . . . . . . .9-38
Sample code to retrieve roles for a given user . . . . . . . . . . . . . . . . . . . . . . . . . . . .9-39
Demonstrations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .9-40
Activities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .9-41
Lesson 9.3. Retrieve work baskets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .9-43
Lesson: Retrieve work baskets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .9-44
Activities that you need to complete . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .9-45
VWWorkbasket object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .9-46
In-baskets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .9-47
In-basket widget . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .9-49
In-baskets tab in Process Designer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .9-50
Specify reference to work queue . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .9-51
In-basket component: displayable columns . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .9-52
In-basket component: runtime filters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .9-53
In-basket component: content filter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .9-54
Steps to retrieve work baskets for a role . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .9-55
vwRole.getWorkBasketReferences() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .9-56
vwQueue.fetchWorkBaskets() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .9-57
Sample code to retrieve work baskets from a role . . . . . . . . . . . . . . . . . . . . . . . . .9-58
Sample code to retrieve work baskets from a queue . . . . . . . . . . . . . . . . . . . . . . .9-59
Steps to retrieve the work basket columns . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .9-60
vwWorkbasket.getColumns() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .9-61
vwColumn.getName() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .9-62
vwColumn.getPrompt() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .9-63
Sample code to get work basket columns . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .9-64
VWWorkBasket.Filter object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .9-65
vwWorkBasket.getFilters() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .9-66
vwFilter.getName() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .9-67
vwFilter.getOperator() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .9-68
Sample code to get work basket filters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .9-69
Demonstrations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .9-70
Activities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .9-72
Lesson 9.4. Query work items from work baskets . . . . . . . . . . . . . . . . . . . . . . . . . . . . .9-73
Lesson: Query work items from work baskets . . . . . . . . . . . . . . . . . . . . . . . . . . . .9-74
Activities that you need to complete . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .9-75
Performing an in-basket query . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .9-76
Example of an in-basket query . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .9-77
Putting it all together - The database query . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .9-78
vwQueue.fetchWorkBasket(...) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .9-79
vwWorkBasket.fetchNextBatch(...) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .9-80
vwWorkBasket.QueryResults.getWorkObjects() . . . . . . . . . . . . . . . . . . . . . . . . . .9-81
vwWorkBasket.QueryResults.getLastRecord() . . . . . . . . . . . . . . . . . . . . . . . . . . .9-82

xii IBM FileNet BPM 5.0: Java API Programming ©Copyright IBM Corp. 2011
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
V5.4.0.3
Student Notebook

TOC Sample code for work basket query . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-83

Sample code to display queue elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-84
Sample code to display column name and value . . . . . . . . . . . . . . . . . . . . . . . . . 9-85
Demonstrations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-86
Activities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-87

Unit 10. Configure Email Notification . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-1

Unit lessons . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-2
Lesson 10.1. Configure email notification . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-3
Lesson: Configure email notification . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-4
Activities that you need to complete . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-5
Email notifications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-6
Steps to configure email notification . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-7
Configure event logging options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-8
Enable notification on VWService . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-9
Configure user preferences . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-10
Configure Process Task Manager . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-12
Deadlines and reminders (1) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-14
Deadlines and reminders (2) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-16
Error opening Step Processor using email . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-17
Demonstrations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-18
Activities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-19
Lesson 10.2. Customize email notification templates . . . . . . . . . . . . . . . . . . . . . . . . . 10-21
Lesson: Customize email notification templates . . . . . . . . . . . . . . . . . . . . . . . . . 10-22
Activities that you need to complete . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-23
Default email notification templates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-24
Location of email notification templates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-25
Email template files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-26
Email notification types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-28
Steps to customize templates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-29
Update the custom templates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-30
Email notification template contents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-31
Optional email notification variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-33
Custom new step notification . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-34
Demonstrations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-35
Activities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-36

©Copyright IBM Corp. 2011 Contents xiii

Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
Student Notebook

xiv IBM FileNet BPM 5.0: Java API Programming ©Copyright IBM Corp. 2011
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
V5.4.0.3
Student Notebook

TMK Trademarks
The reader should recognize that the following terms, which appear in the content of this
training document, are official trademarks of IBM or other companies:
IBM® and the IBM logo are registered trademarks of International Business Machines
Corporation.
The following are trademarks of International Business Machines Corporation, registered in
many jurisdictions worldwide:
Cognos® DB2® FileNet®
WebSphere®
Java and all Java-based trademarks and logos are trademarks of Sun Microsystems, Inc.
in the United States, other countries, or both.
Linux® is a registered trademark of Linus Torvalds in the United States, other countries, or
both.
Microsoft and Windows are trademarks of Microsoft Corporation in the United States, other
countries, or both.
UNIX® is a registered trademark of The Open Group in the United States and other
countries.
Other product and service names might be trademarks of IBM or other companies.

© Copyright IBM Corp. 2011 Trademarks xv

Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
Student Notebook

xvi IBM FileNet BPM 5.0: Java API Programming © Copyright IBM Corp. 2011
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
V5.4.0.3
Student Notebook

pref Course description

IBM FileNet Business Process Manager 5.0: Java API Programming

Duration: 4 days

Overview
This course provides information about Process Java API methods for
developing custom applications that access the IBM FileNet P8
Process Engine. In order to practice these skills, you write code using
Process Java API and work with a fully functioning IBM FileNet
Business Process Manager system.

Audience
This course is for those whose job responsibilities include designing
and developing of custom BPM applications, and those who need to
know the capabilities of the Process Java API.

Prerequisites
Basic programming experience in Java-based technologies
Familiarity with business process management and workflow concepts
IBM FileNet P8 5.0 Prerequisite Skills using Workplace XT (F141)
IBM FileNet BPM 5.0: Administration (F144) - recommended
IBM FileNet BPM 5.0: Process Design (F145) - recommended

Skills taught
How to develop applications using IBM FileNet P8 Process Engine
Java API libraries.

Contents
• Introduction to IBM FileNet Business Process Manager
• Overview of Process objects and Process Java API
• Retrieve and launch Workflows.
• Retrieve and set the step element parameters.
• Automatically launch a worflow using workflow subscription.

© Copyright IBM Corp. 2011 Course description xvii

Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
Student Notebook

• Search for work by querying a workflow roster, queue and event

log.
• Process work items.
• Retrieve workflow history and milestones information.
• Implement Content Extended Operations in a workflow.
• Write Java code for a component and create a component queue.
• Retrieve application spaces, roles and in-basket information.
• Process work items from in-baskets.
• Configure the Process Engine for email notification
• Launch a workflow and test email notification
• Customize email notification templates.

xviii IBM FileNet BPM 5.0: Java API Programming © Copyright IBM Corp. 2011
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
V5.4
Student Notebook

Uempty Unit 1. IBM FileNet Business Process Manager

Introduction

What this unit is about

This unit introduces you to fundamental workflow elements and how
they are used in IBM FileNet BPM solutions.
You learn about process work management features and process
automation and connectivity features for the IBM FileNet BPM solution
that you support.
You also learn about the architectural components of an IBM FileNet
BPM system and their functions.

What you should be able to do

After completing this unit, you should be able to:
• Identify workflow concepts.
• Prepare your system for the student exercises.
• Identify elements in a workflow definition.
• Launch, process, and track a workflow.
• Identify functions of IBM FileNet BPM components.
• View workflow database information.

How you will check your progress

• Successfully complete the activities in the Student Exercises book.

References
www.ibm.com/support/documentation/us/en (Support & downloads
page)
Note: IBM FileNet products belong to the Information Management
product set.

© Copyright IBM Corp. 2011 Unit 1. IBM FileNet Business Process Manager Introduction 1-1
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
Student Notebook

IBM FileNet Business Process Manager Introduction

Unit lessons
This unit contains these lessons:
• Workflow fundamentals
• Workflow processing
• IBM FileNet BPM architecture

© Copyright IBM Corporation 2011

Figure 1-1. Unit lessons F1561.0

Notes:
Lessons in this unit
This unit has three lessons. After the first lesson, each lesson relies on information and
skills taught in the prior lessons. For best results, do these lessons in the sequence
presented.
Workflow fundamentals – In this lesson, you become familiar with fundamental workflow
elements and how they are used in IBM FileNet BPM solutions.
Workflow processing – In this lesson, you learn about how workflow is processed in an
IBM FileNet BPM solution. You launch, process, and track a workflow. You view the history
of workflow processing event.
IBM FileNet BPM architecture – In this lesson, you identify the architectural components
of an IBM FileNet BPM system and identify their functions.

1-2 IBM FileNet BPM 5.0: Java API Programming © Copyright IBM Corp. 2011
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
V5.4
Student Notebook

Uempty Lesson 1.1. Workflow fundamentals

© Copyright IBM Corp. 2011 Unit 1. IBM FileNet Business Process Manager Introduction 1-3
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
Student Notebook

Lesson:
Workflow fundamentals
• Why is this lesson important to you?
– As a programmer, you develop business process applications using
Process Engine Java API. You want to be familiar with fundamental
workflow elements and how they are used in IBM FileNet BPM
solutions.

© Copyright IBM Corporation 2011

Figure 1-2. Workflow fundamentals F1561.0

Notes:

1-4 IBM FileNet BPM 5.0: Java API Programming © Copyright IBM Corp. 2011
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
V5.4
Student Notebook

Uempty
Workflow fundamentals
Activities that you need to complete
• Identify workflow concepts.
• Prepare your system for the student exercises.
• Identify elements in a workflow definition.

© Copyright IBM Corporation 2011

Figure 1-3. Activities that you need to complete F1561.0

Notes:
These are the activities that you are going to perform in this lesson.

© Copyright IBM Corp. 2011 Unit 1. IBM FileNet Business Process Manager Introduction 1-5
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
Student Notebook

Workflow fundamentals
Process automation with IBM FileNet BPM
• IBM FileNet BPM automates the routing and processing of
work in an enterprise.
– The Process Engine (PE) contains software and database structures
that run and manage automated processes.
– A business process is implemented as a workflow that is managed by
the Process Engine.
• Users participate in the process as follows:
– At specified steps in the process that are routed to the user
– By performing the tasks required for a step
• Workflow solution builders and administrators do the following:
– Configure the Process Engine.
– Manage running workflows.
– Help workflow participants.

© Copyright IBM Corporation 2011

Figure 1-4. Process automation with IBM FileNet BPM F1561.0

Notes:
Help path
• IBM FileNet P8 Version 5.0 Information Center > Integrating workflow into document
management > Getting Started with FileNet Process applications

1-6 IBM FileNet BPM 5.0: Java API Programming © Copyright IBM Corp. 2011
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
V5.4
Student Notebook

Uempty
Workflow fundamentals
Workflows and workflow definitions
• A workflow is a unique instance, or case, of a process
managed by the Process Engine.
– Work is performed by individuals or resources, serially or in parallel, to
accomplish a business process.
– A workflow contains steps, properties, and routing information
maintained in an executable form.
• A workflow definition is representation of a business process
used as a template for creating workflows.
– Represents a series of tasks, shown as steps, connected by routes.
– Identifies activities, resources, participants, and conditions needed to
process the work.
– Stored as a .pep (XML) or XPDL file on the Content Engine.
• A workflow is a unique instance of a workflow definition.

© Copyright IBM Corporation 2011

Figure 1-5. Workflows and workflow definitions F1561.0

Notes:
This page is a review of workflow concepts that you learned in the IBM FileNet P8
Prerequisite Skills course, which is prerequisite learning for this course. In order to support
or deploy workflow applications in an IBM FileNet BPM solution, you must understand the
difference between a workflow definition and an instance of a workflow.
Workflow
A workflow is an electronic package of a business process that includes routing and
content information needed to process the work. In IBM FileNet P8, a workflow is managed
by the Process Engine, one of the IBM FileNet P8 core components. The work consists of
electronic objects sent to recipients (human participants or machines). At every point, the
system tracks the work so that it cannot be lost.
Workflow definition
A workflow definition is stored in the Content Engine as an XML or XPDL file. A workflow
author uses Process Designer to create the workflow definition. You can think of a workflow

© Copyright IBM Corp. 2011 Unit 1. IBM FileNet Business Process Manager Introduction 1-7
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
Student Notebook

definition as a processing template for creating workflows. The Process Engine uses
information from the workflow definition each time a workflow is launched and runs.
A workflow definition is a file that specifies the following items:
• Steps required to accomplish a business process
• Routes that determine the sequence of steps
• Participants, fields, and attachments that are needed to complete each step
• Responses that the participant can choose
For example, a workflow definition was created that models a loan processing application.
When John Smith, a customer, applies for a loan, a new workflow is created and launched
using the workflow definition as a template. The workflow includes loan information
applicable to John Smith’s loan, such as data field values, attached documents, and so
forth.
Multiple workflow definition
A workflow definition file that is stored as an XPDL file can be built to contain multiple
workflow definitions. This multiple workflow definition file is known as a workflow collection.
Workflow authors use Process Designer to create workflow definition files that are saved
on the Content Engine. The files are versioned as the workflow definitions are modified.

1-8 IBM FileNet BPM 5.0: Java API Programming © Copyright IBM Corp. 2011
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
V5.4
Student Notebook

Uempty
Workflow fundamentals
Process Designer
• Graphical tool used to
create workflow
definitions
– Define workflow maps,
steps, and routes
– Define data fields,
attachments, milestones, Work area shows
route conditions, and so the current map
forth
– Used by:
• Workflow designer and
business analyst
• Solution builder Object properties
pane

© Copyright IBM Corporation 2011

Figure 1-6. Process Designer F1561.0

Notes:
Help paths
• IBM FileNet P8 Version 5.0 Information Center > Integrating workflow into document
management > Process Designer
• IBM FileNet P8 Version 5.0 Information Center > Integrating workflow into document
management > Process Designer > Getting started in Design mode > About defining a
workflow
The screen capture on this page shows the Process Designer diagram mode user
interface. The interface has a menu of commands, a toolbar of commonly used commands,
a map area to diagram a business process using steps and routes, and the object
properties pane to configure the steps and routes.
Workflow authors can use Process Designer to do the following:
• Build workflow maps by adding steps and routes.
• Define required data fields for each step, such as loan ID or customer.

© Copyright IBM Corp. 2011 Unit 1. IBM FileNet Business Process Manager Introduction 1-9
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
Student Notebook

• Create placeholders for content-related attachments.

Process Designer is used by the workflow designer, business analyst, and solution builder.
Business analysts also use Process Designer for process simulation. Some options allow
for integration of custom code into a workflow solution.
Process Designer has two modes of operation: Diagram mode and Design mode.

1-10 IBM FileNet BPM 5.0: Java API Programming © Copyright IBM Corp. 2011
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
V5.4
Student Notebook

Uempty
Workflow fundamentals
Workflow maps
• Contain steps and routes
• Main map (called Workflow) and submaps
• Step types
– Activity queue step
– Activity participant step
– Submap step
– System step
– Component step

© Copyright IBM Corporation 2011

Figure 1-7. Workflow maps F1561.0

Notes:
Help paths
• IBM FileNet P8 Version 5.0 Information Center > Integrating workflow into document
management > Process application concepts > Designing and running workflows >
About workflow maps
• IBM FileNet P8 Version 5.0 Information Center > Integrating workflow into document
management > Process Designer > Getting started in Design mode > Workflow map
area for Design mode
In Process Designer, a workflow definition is built with steps and routes to define one or
more workflow maps. The main map in a workflow is called the Workflow map.
A map might contain several different types of steps:
• An activity queue step specifies the queue that will be used.
• An activity participant step is processed by a specified individual or group of individuals
• A submap step calls another workflow map.

© Copyright IBM Corp. 2011 Unit 1. IBM FileNet Business Process Manager Introduction 1-11
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
Student Notebook

• A system step calls a system function.

• A component step executes an external operation.
The diagram on this page shows an example main map from a workflow definition. The
map contains a LaunchStep, four routes shown by arrows, and three steps. Two
conditional routes are shown: [1] Verified and [2] Not Verified. When the workflow definition
is launched, a workflow is created and processed based on the map.

1-12 IBM FileNet BPM 5.0: Java API Programming © Copyright IBM Corp. 2011
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
V5.4
Student Notebook

Uempty
Workflow fundamentals
Step and workflow properties
• Each step has properties that vary by step type.
– General
– Parameters
– Routing
– Assignments
– Deadline

• Entire workflow has properties that are assigned.

– Name and subject
– Attachments (documents, folders, custom objects)
– Data fields
– Other information that affects workflow behavior

© Copyright IBM Corporation 2011

Figure 1-8. Step and workflow properties F1561.0

Notes:
Help paths
• IBM FileNet P8 Version 5.0 Information Center > Integrating workflow into document
management > Process Designer > About steps > Working with steps > Specify step
properties
• IBM FileNet P8 Version 5.0.0 System Overview
Note: The System Overview file is a reference document that you can access from this
link:
http://www-05.ibm.com/e-business/linkweb/publications/servlet/pbi.wss?CTY=US&FN
C=SRX&PBL=SC19-3237-00
Each step or route on a workflow map has properties assigned to it, which affect the
behavior of the workflow during execution. The screen capture on this page shows the
Process Designer object properties pane that is used to configure step or route properties
in a workflow definition. The tabs displayed depend upon the type of step or route selected

© Copyright IBM Corp. 2011 Unit 1. IBM FileNet Business Process Manager Introduction 1-13
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
Student Notebook

on the workflow map. You use the object properties pane to define and edit the workflow
step or route properties.
In addition, the Workflow Properties tabs show the properties that apply to the entire
workflow. In the Workflow Properties tab, the workflow author defines the name of the
workflow, subject, data fields, attachments, workflow groups, milestones, and so forth.

1-14 IBM FileNet BPM 5.0: Java API Programming © Copyright IBM Corp. 2011
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
V5.4
Student Notebook

Uempty
Workflow fundamentals
Work items
• Work items are units of work in a running workflow.
– Work items contain the data and instructions needed for processing.
– The system uses work items to keep track of the workflow process.
• One or more work items are associated with each step in a
workflow being processed.

This step has one This step has three

work item processed work items processed
by one participant. by three participants.

© Copyright IBM Corporation 2011

Figure 1-9. Work items F1561.0

Notes:
Help path
• IBM FileNet P8 Version 5.0 Information Center > Integrating workflow into document
management > Process Administrator > About searching for workflows and events >
About workflows vs. work items
A work item is a collection of data and references to system information needed to
process the work.
A work item is transitory. It ceases to exist after it is processed.
A work item is placed in a Process Engine queue during processing. The participants
assigned to process a work item select the work item from the queue. (Queues are
described on the next page.) A work item is the smallest individual piece of a workflow.
Each workflow has one or more work items associated with it, depending on the business
process. For example, if a workflow has a step assigned to three participants (a
multiparticipant step), four work items are created for processing that step. One work item
is placed in the Inbox queue of each of the three participants and the parent work item is

© Copyright IBM Corp. 2011 Unit 1. IBM FileNet Business Process Manager Introduction 1-15
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
Student Notebook

placed in a Delay queue. After all three participants have completed the work, the work
item data is updated in the parent work item. Then, the parent work item moves to the next
step in the workflow. This example is illustrated in the workflow map on this page.
Work items can be processed by various participants including enterprise users,
customers, partners, or applications.

1-16 IBM FileNet BPM 5.0: Java API Programming © Copyright IBM Corp. 2011
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
V5.4
Student Notebook

Uempty
Workflow fundamentals
Queues
• A queue is a database structure where work items are
maintained while awaiting processing by one of the following:
– The system
– Applications
– Workflow participants (users)
• Each workflow application uses multiple queues.
• Queues are created and configured by the solution builder.
• Types of queues:
– User queue is for an individual (examples: Inbox, Tracker).
– Work queue is for a group (examples: Clerk, Manager).
– Component queue is for automated processing.
– System queue is for system activities (example: Delay).

© Copyright IBM Corporation 2011

Figure 1-10. Queues F1561.0

Notes:
Help path
• IBM FileNet P8 Version 5.0 Information Center > Integrating workflow into document
management > Process Configuration Console > About queues
Queues are specified in the workflow definition.
Example: A workflow participant who is a bank officer sees work in the LoanOfficer queue.
Work is managed in queues, which are database structures that hold work items.
For example:
• User queues hold work items assigned to and waiting to be processed by a specific
user. The user queue is called My Inbox in Workplace, and provides users with tasks
that users need to perform.
• Tracker in Workplace holds tracker work items that reference the running workflows
that are monitored by the user.

© Copyright IBM Corp. 2011 Unit 1. IBM FileNet Business Process Manager Introduction 1-17
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
Student Notebook

• A Work Queue (also called Public Inboxes in Workplace) holds work items that are
associated with a specific user group and that are waiting to be processed by any user
in the assigned group. The screen capture shows a number of queue tables in the
Process Engine database.
Some steps are not completed by participants. These work items go into system or
component queues, not into participant queues. Other queues are used by the system and
applications.
For example:
• Component queues hold work items that can be automated using external
components, like Java classes.
• System queues hold work items that are being processed by the Process Engine or
that are waiting for processing by the Process Engine.

1-18 IBM FileNet BPM 5.0: Java API Programming © Copyright IBM Corp. 2011
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
V5.4
Student Notebook

Uempty
Workflow fundamentals
Workflow rosters
• A roster is a database structure used to keep track of work items.
• Each workflow application uses one workflow roster.
• A roster contains references to all running workflows and work
items for the application.
– Rosters provide an efficient way to search for specific work items.
– Solution builders create and configure rosters.
– Workflow administrators use rosters to search for, process, and
manage work items. QueueA
»
Workflow roster
»
A reference to
each work item »
is maintained in The work items
the roster. are maintained
QueueB in queues.
»

© Copyright IBM Corporation 2011

Figure 1-11. Workflow rosters F1561.0

Notes:
Help path
• IBM FileNet P8 Version 5.0 Information Center > Integrating workflow into document
management > Process Configuration Console > Configure workflow rosters
A workflow roster (also referred to as a roster) is similar to a master index. It contains the
current location and other configurable information about all active workflows and work
items.
For each workflow definition, one workflow roster is assigned in the Workflow Properties in
Process Designer. All workflows launched using the workflow definition use this assigned
workflow roster.
DefaultRoster is the name of the default roster created by the system when an isolated
region is initialized. The workflow solution builder creates additional rosters as needed.
When a workflow instance is created, it is assigned a unique workflow number and
registered in the workflow roster associated with its workflow definition.
Example of multiple rosters

© Copyright IBM Corp. 2011 Unit 1. IBM FileNet Business Process Manager Introduction 1-19
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
Student Notebook

A roster with a unique name is created for each departmental group that uses a workflow
application (for example, MarketingRoster, AccountingRoster, LoanRoster). Multiple
rosters make it easier to search for and manage the work items for each department.
The Diagram represents work items represented in Rosters and in Queues.

1-20 IBM FileNet BPM 5.0: Java API Programming © Copyright IBM Corp. 2011
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
V5.4
Student Notebook

Uempty
Workflow fundamentals
Workflow history and statistics
• Event logs keep a record of workflow history.
– Specific system- or workflow-related events are useful for tracking
workflow activity.
– Solution builders create and configure event logs and enable event
logging in Process Configuration Console.
– Workflow administrators maintain and use event logs to view
historical workflow information.
– Event logs are used by other tools:
• IBM FileNet Case Analyzer analyzes workflow events.
• WebSphere Business Monitor monitors active processes.
• Statistics
– Use IBM FileNet Case Analyzer for collection and analysis of
workflow processing statistics.
– Case Analyzer is enabled in Process Configuration Console.

© Copyright IBM Corporation 2011

Figure 1-12. Workflow history and statistics F1561.0

Notes:
Help paths
• IBM FileNet P8 Version 5.0 Information Center > Integrating workflow into document
management > Process application concepts > Events > About event logs
• IBM FileNet P8 Version 5.0 Information Center > Integrating workflow into document
management > IBM FileNet Case Analyzer User Guide
Event logs are database structures on the Process Engine that collect workflow event
information, such as work item creation, termination, begin service, and end service. Event
logs are used in reports and tools to display workflow history.
IBM FileNet Case Analyzer allows you to generate dynamic, chart-based reports from
statistical information gathered from the Process Engine, Content Engine, and Process
Simulator. The reports summarize information about active (running) cases and workflows,
as well as historical data. The information can be provided as IBM Cognos 8 Business
Intelligence reports or Microsoft Excel spreadsheets (pivot charts). Case Analyzer helps
you to analyze and manage case and workflow processes. Workflow data fields that are

© Copyright IBM Corp. 2011 Unit 1. IBM FileNet Business Process Manager Introduction 1-21
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
Student Notebook

exposed on the event log can be read by Case Analyzer. The Case Analyzer is configured
to read these data fields by using the Process Task Manager on the Process Engine. Case
Analyzer is covered in another course.

1-22 IBM FileNet BPM 5.0: Java API Programming © Copyright IBM Corp. 2011
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
V5.4
Student Notebook

Uempty
Workflow fundamentals
Demonstrations
• View a workflow definition in Process Designer.

© Copyright IBM Corporation 2011

Figure 1-13. Demonstrations F1561.0

Notes:
Demonstration notes:
This demonstration shows how to work with the elements of a workflow definition file in
Process Designer.
1. You are already signed in to Workplace XT as the Administrator user.
2. Click the Loan Processing Workflow file located in the LoanProcess object store >
Workflows folder. Process Designer opens.
3. In Process Designer, notice the map area where the Workflow main map is displayed.
4. Notice the functional areas of Process Designer:
- Menu bar
- Main tool bar
- Map tool bar with list of submaps.
- Object properties pane.

© Copyright IBM Corp. 2011 Unit 1. IBM FileNet Business Process Manager Introduction 1-23
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
Student Notebook

5. In the object properties pane, explore the Workflow Properties the tabs. Notice the
workflow name in the General tab.
6. Select the PrepareLoanMap submap from the map toolbar list of maps.
7. Select the Confirm Information step and notice that it is a Participant step.
a. Verify that Participants is selected in the Properties Pane > General tab > Step
Destination area.
b. Verify that the participant name listed is LoanOfficers, a workflow group.
8. Select the Confirm Rate & Payment step and verify that it is a Work Queue step.
a. Verify that Work Queue is selected in the Properties Pane > General tab > Step
Destination area.
b. Verify that the selected queue name is LoanCustomer.
9. In the Properties pane > Parameters tab, examine the lists of available and selected
parameters.
10. Exit Process Designer and cancel the checkout.
11. Close the applet window.

1-24 IBM FileNet BPM 5.0: Java API Programming © Copyright IBM Corp. 2011
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
V5.4
Student Notebook

Uempty
Workflow fundamentals
Activities
• In your Student Exercises
• Unit: IBM FileNet Business Process Manager
Introduction
• Lesson: Workflow fundamentals
• Activities:
– Identify workflow concepts.
– Prepare your system for the student exercises.
– Identify elements in a workflow definition.

© Copyright IBM Corporation 2011

Figure 1-14. Activities F1561.0

Notes:
Use your Student Exercises to perform the activities listed.

© Copyright IBM Corp. 2011 Unit 1. IBM FileNet Business Process Manager Introduction 1-25
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
Student Notebook

1-26 IBM FileNet BPM 5.0: Java API Programming © Copyright IBM Corp. 2011
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
V5.4
Student Notebook

Uempty Lesson 1.2. Workflow processing

© Copyright IBM Corp. 2011 Unit 1. IBM FileNet Business Process Manager Introduction 1-27
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
Student Notebook

Lesson:
Workflow processing
Why is this lesson important to you?
• Your IBM FileNet BPM solution includes numerous workflow
processing features. As a programmer, you want to be familiar
with how to launch, process, and track a workflow. You want to
know how to view the history of workflow processing events.

© Copyright IBM Corporation 2011

Figure 1-15. Workflow processing F1561.0

Notes:

1-28 IBM FileNet BPM 5.0: Java API Programming © Copyright IBM Corp. 2011
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
V5.4
Student Notebook

Uempty
Workflow processing
Activities that you need to complete
• Launch, process, and track a workflow.

© Copyright IBM Corporation 2011

Figure 1-16. Activities that you need to complete F1561.0

Notes:
These are the activities that you are going to perform in this lesson.

© Copyright IBM Corp. 2011 Unit 1. IBM FileNet Business Process Manager Introduction 1-29
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
Student Notebook

Workflow processing
Workflow processing
• What happens when a workflow is launched
– A work item is created and placed in the first queue, as designated
by the workflow definition.
– A reference to the workflow is created and maintained in a workflow
roster.
• What happens while the work is processed
– Work items move from queue to queue as defined by the workflow
definition.
– The workflow roster is updated as work items are processed.
– Process events are recorded in an event log.
• What happens when the process is complete
– The Terminate submap is called and any steps are executed.
– All work items are removed from the system.
– A history of the work remains in an event log.
© Copyright IBM Corporation 2011

Figure 1-17. Workflow processing F1561.0

Notes:
This page summarizes what happens inside the Process Engine during workflow
processing.
A workflow solution builder and workflow administrator need to know this information in
order to effectively use the workflow administrative tools, such as Process Configuration
Console and Process Administrator, to deploy and manage workflows.

1-30 IBM FileNet BPM 5.0: Java API Programming © Copyright IBM Corp. 2011
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
V5.4
Student Notebook

Uempty
Workflow processing
How workflows are launched
• A workflow can be launched by one of the following:
– An event (through a subscription)
– An entry template
– Custom code
– A user (manually through Workplace XT or Workplace)
– Process Designer (for testing)
– Other applications (Example: Records Manager, Case Builder
Runtime)
• Each workflow triggers the business activities for the steps in
the process.

© Copyright IBM Corporation 2011

Figure 1-18. How workflows are launched F1561.0

Notes:
Each workflow can be launched by the following:
Event subscription – Example: A new loan is added to the CE Object Store. When the
creation event occurs, a loan processing workflow is launched.
An entry template – Example: An entry template is used to capture a customer’s loan
information as his loan application is added to the CE Object Store. During that process,
the loan processing workflow is launched.
Custom code
A user – Example: Loan Processors can launch a credit check workflow to obtain credit
information about a customer. They can launch this workflow manually through Workplace
or Workplace XT.
Process Designer – Example: A business analyst is creating and configuring a workflow
definition. To test the workflow, the analyst validates, transfers, and launches the workflow.

© Copyright IBM Corp. 2011 Unit 1. IBM FileNet Business Process Manager Introduction 1-31
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
Student Notebook

Other Applications – Example: Records Manager Add-On provides a number of predefined

workflows to do a task such as approve a Destroy action. Case Builder Runtime allows a
case task to be launched using mashup pages and an ECM toolbar widget.

1-32 IBM FileNet BPM 5.0: Java API Programming © Copyright IBM Corp. 2011
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
V5.4
Student Notebook

Uempty
Workflow processing
Inboxes, work queues, and step processors
• An Inbox holds work items that are to be processed by a
specific user.
• A work queue holds work items that are to be processed by a
specific user group.
• A native user interface, called step processor, is associated
with the Inbox and work queues.
• Step processors can be customized as any of the following:
– HTML page
– Java application or Applet
– eForms
– Mashup pages using ECM Widgets
• Lotus Mashups
• WebSphere Business Space

© Copyright IBM Corporation 2011

Figure 1-19. Inboxes, work queues, and step processors F1561.0

Notes:
Help paths
• IBM FileNet P8 Version 5.0 Information Center > Integrating workflow into document
management > Process application concepts > Designing and running workflows >
About step processors
• IBM FileNet P8 Version 5.0 Information Center > Integrating workflow into document
management > Java step processor
Example: A company with a department of clerks might have a Clerical Department Work
inbox, which is a group inbox.
Work is managed in queues, which are database structures that hold work items waiting to
be processed.
• User queues:
- Hold work items that are waiting to be processed by a specific user.
- Are called My Inbox in Workplace.

© Copyright IBM Corp. 2011 Unit 1. IBM FileNet Business Process Manager Introduction 1-33
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
Student Notebook

• Public Inbox:
- Is associated with a specific group of users.
- Holds work items that are waiting to be processed by any user in the assigned
group.
• Inboxes and work queues present and filter a user’s or a group’s work. Users can do the
following tasks:
- Process work items.
- View workflow milestones and launched workflows.
• Native user Interfaces or “step processors” are preconfigured in the Process
Configuration console for each isolated region. Additional step processors can be
added including HTML pages, Java pages, eForms, and Mashup pages using ECM
Widgets.

1-34 IBM FileNet BPM 5.0: Java API Programming © Copyright IBM Corp. 2011
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
V5.4
Student Notebook

Uempty
Workflow processing
Process tracking
• Process Tracker
– View progress
of workflows
and work item
tasks.
• Business
purpose of
process tracking
– Address
process
bottlenecks.
– Prevent
delays.

© Copyright IBM Corporation 2011

Figure 1-20. Process tracking F1561.0

Notes:
Help path
• IBM FileNet P8 Version 5.0 Information Center > Integrating workflow into document
management > Process Tracker
The screen capture on this page shows a sample Process Tracker screen containing a
workflow in progress. The check mark icon over LaunchStep and Verify Info step means
that these steps were completed. The hourglass icon over the Modify Info step means that
this step is the next step to be processed. The unlock icon means that the work is not
currently being processed.
Process Tracker allows a workflow author, BPM administrator, or business manager to
trace the execution of a workflow at each step until all processing steps have completed.
The information in Process Tracker is generated from the events that take place during the
execution of the workflow. After the workflow terminates and the Process Tracker window is
closed, all that remains are the event log messages saved in the event log. After the
workflow terminates, the user can no longer open a visual picture of the workflow in the
Process Tracker tool.

© Copyright IBM Corp. 2011 Unit 1. IBM FileNet Business Process Manager Introduction 1-35
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
Student Notebook

Workflow processing
Search for work in Process Administrator
4. Execute
1. Select 2. Select search (or
search target. search mode. count only).

Search
pane

3. Select search
criteria and results
options (optional).
Separator
bar
Results
5. View and use pane
search results.

© Copyright IBM Corporation 2011

Figure 1-21. Search for work in Process Administrator F1561.0

Notes:
Help path
• IBM FileNet P8 Version 5.0 Information Center > Integrating workflow into document
management > Process Administrator > Getting started > How Process Administrator is
organized
User interface of Process Administrator
The screen capture on this page shows the user interface of Process Administrator. At the
top, this user interface displays the search pane for setting search criteria and, at the
bottom, displays the results pane for viewing search results. A separator bar permits you to
change relative sizes of each pane depending on your needs.
Search pane
The search target specifies the kind of database object to be searched for. You can select
from all objects for which you have security privileges.
The Find Now option starts the defined search.

1-36 IBM FileNet BPM 5.0: Java API Programming © Copyright IBM Corp. 2011
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
V5.4
Student Notebook

Uempty The Search Count option returns a quick estimate of work items that meet the search
criteria.
The New Search option clears the search criteria.
Results pane
The results of a search are displayed in the results pane in a tabular format. Depending on
the options selected, each row in the table represents a workflow, a work item, or an event
from the event log.
The information is displayed in sets of rows. You can view subsequent sets by clicking the
Next Set icon on the results pane toolbar.
Separator bar
Use the separator bar to hide, display, or change the size of the search specification and
results panes. Click the up arrow on the separator bar to hide the top pane and expand the
bottom pane. Click the down arrow to do the reverse. To change the relative size of both
panes, drag the bar up or down.
You learn more about advanced searching techniques for Process Administrator in another
lesson in this course.

© Copyright IBM Corp. 2011 Unit 1. IBM FileNet Business Process Manager Introduction 1-37
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
Student Notebook

Workflow processing
Search targets
• Use Process Administrator to run precision searches.
– Select the area to be searched and select the search target.
– Available target objects are limited by your access rights.
– For Tracker or Inbox, you can limit search to specific users.
Search target
Area to search
Workflows Work items Events
Workflow roster X X
User queue X

Work queue X
System queue X
Event log X
© Copyright IBM Corporation 2011

Figure 1-22. Search targets F1561.0

Notes:
Help path
• IBM FileNet P8 Version 5.0 Information Center > Integrating workflow into document
management > Process Administrator > About searching for workflows and events
Use the extensive search capabilities of Process Administrator to perform precision
searches by specifying an area to search and the workflow element that you want to locate.
This table lists the possible Process Engine data structures to be searched under the Area
to search column: workflow roster, user queue, work queue, system queue, and event log.
The X symbol indicates the search targets (workflows, work items, events) that can be
searched for each area.
If you select the Inbox or Tracker user queue, you can limit the search to work belonging to
selected users. By default, work belonging to all users is searched when no users are
selected. Use the Users tab to select specific users.
Your access rights to the Process Engine structures determine which target objects are
available to select.

1-38 IBM FileNet BPM 5.0: Java API Programming © Copyright IBM Corp. 2011
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
V5.4
Student Notebook

Uempty
Workflow processing
Milestones, deadlines, and timers
• Milestones selectively expose the status of workflow steps.
– Milestones expose status by step and by access level.
– Users have access to necessary information when they need it.
• Deadlines set automated, time-based checks on steps,
workflows, or both.
– Each deadline is relative to a specified time.
– A reminder can be sent for each deadline at a specified time.
– If a deadline is reached, a specified submap can be launched.
• Timers are automated, time-based checks during workflows
processing.
– If a timer expires, a specified submap can be launched.
– Multiple timers can be active within a workflow.

© Copyright IBM Corporation 2011

Figure 1-23. Milestones, deadlines, and timers F1561.0

Notes:
Help path
• IBM FileNet P8 Version 5.0 Information Center > Integrating workflow into document
management > Process applications concepts > Designing and running workflows >
About milestones
When the workflow definition is created, several options can be added to control user
interaction and the timeliness and flow of steps processed in the workflow. This page
discusses three of these control features: milestones, deadlines, and timers.

© Copyright IBM Corp. 2011 Unit 1. IBM FileNet Business Process Manager Introduction 1-39
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
Student Notebook

Workflow processing
Process connectivity features
• Process orchestration using XML Web Services
– Can call a web service
– Can create a workflow-based web service
• Database connectivity
– Integrate BPM applications with existing databases
– Retrieve, update, or record data using workflows
• Component integration (Java or JMS)
– Used to hand off processing to existing business applications

© Copyright IBM Corporation 2011

Figure 1-24. Process connectivity features F1561.0

Notes:
Reference
• IBM FileNet P8 System Overview, V5.0
(http://www-05.ibm.com/e-business/linkweb/publications/servlet/pbi.wss?CTY=US&FN
C=SRX&PBL=SC19-3237-00), see Process management “Connectivity” section
A workflow definition can make use of options to connect to external processes or services.
The diagram on this page shows an example process map containing a LaunchStep and
three system steps that provide access to external programs from a workflow definition.
The Component step can execute Java code, use CE_Operations to access content
information on the Content Engine, and put information into a Java Messaging queue. The
Invoke step can call a web service to run and can receive information from the service. The
DbExecute step can run a stored procedure in a database.

1-40 IBM FileNet BPM 5.0: Java API Programming © Copyright IBM Corp. 2011
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
V5.4
Student Notebook

Uempty
Workflow processing
Activities
In your Student Exercises
• Unit: IBM FileNet Business Process Manager
Introduction
• Lesson: Workflow processing
• Activities:
– Launch, process, and track a workflow.

© Copyright IBM Corporation 2011

Figure 1-25. Activities F1561.0

Notes:
Use your Student Exercises to perform the activities listed.

© Copyright IBM Corp. 2011 Unit 1. IBM FileNet Business Process Manager Introduction 1-41
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
Student Notebook

1-42 IBM FileNet BPM 5.0: Java API Programming © Copyright IBM Corp. 2011
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
V5.4
Student Notebook

Uempty Lesson 1.3. IBM FileNet BPM architecture

© Copyright IBM Corp. 2011 Unit 1. IBM FileNet Business Process Manager Introduction 1-43
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
Student Notebook

Lesson:
IBM FileNet BPM architecture
Why is this lesson important to you?
• Your IBM FileNet BPM solution runs on a multiserver,
distributed system. Because you build, deploy, or support this
solution, you need to communicate with your team members
about the specific purpose and function of the BPM
architectural components of your solution.

© Copyright IBM Corporation 2011

Figure 1-26. IBM FileNet BPM architecture F1561.0

Notes:

1-44 IBM FileNet BPM 5.0: Java API Programming © Copyright IBM Corp. 2011
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
V5.4
Student Notebook

Uempty
IBM FileNet BPM architecture
Activities that you need to complete
• Identify functions of IBM FileNet BPM components.
• View workflow database information.

© Copyright IBM Corporation 2011

Figure 1-27. Activities that you need to complete F1561.0

Notes:
These are the activities that you are going to perform in this lesson.

© Copyright IBM Corp. 2011 Unit 1. IBM FileNet Business Process Manager Introduction 1-45
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
Student Notebook

IBM FileNet BPM architecture

Principal components of IBM FileNet BPM
• Process Engine (PE)
– Engine that executes and manages workflows
• Rules Connectivity Framework (RCF)
– Software to create and add business rules to workflows
– Allows a user to change business processing requirements without
modifying workflow definitions
• Case Analyzer (CA)
– Engine that enables collection, analysis, and reporting on production
and simulated process data
• Process Simulator (PS)
– Engine that simulates workflow processing and allows users to create
“what-if” business scenarios
– Used to analyze process and workload changes

© Copyright IBM Corporation 2011

Figure 1-28. Principal components of IBM FileNet BPM F1561.0

Notes:
Help paths
• IBM FileNet P8 Version 5.0 Information Center > Integrating workflow into document
management > Designing and running workflows > Integrating business rules
• IBM FileNet P8 Version 5.0 Information Center > Integrating workflow into document
management > IBM FileNet Case Analyzer User Guide
• IBM FileNet P8 Version 5.0 Information Center > Integrating workflow into document
management > Process Simulator
• IBM FileNet P8 System Overview, V5.0
(http://www-05.ibm.com/e-business/linkweb/publications/servlet/pbi.wss?CTY=US&FN
C=SRX&PBL=SC19-3237-00)
This page identifies the key BPM components. These four components perform the bulk of
BPM and workflow-related processing.
The Rules Connectivity Framework (RCF) is used to implement business rules for
workflows.

1-46 IBM FileNet BPM 5.0: Java API Programming © Copyright IBM Corp. 2011
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
V5.4
Student Notebook

Uempty
IBM FileNet BPM architecture
Other FileNet BPM software components
• Workflow database
• Component Integrator
• Process Task Manager (PTM)
• Process-related tools
• Email notification

© Copyright IBM Corporation 2011

Figure 1-29. Other FileNet BPM software components F1561.0

Notes:
This page introduces other IBM FileNet BPM components. More information on each
component is provided in the following pages and in other lessons in this course.
Instructions on how to configure a BPM system for email notification of workflow events is
covered in another unit in this course.
Process Task Manager can be started on a UNIX machine by running the VWtaskman.sh
file, or it can be started on a Windows system by running the VWTaskman.bat file.

© Copyright IBM Corp. 2011 Unit 1. IBM FileNet Business Process Manager Introduction 1-47
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
Student Notebook

IBM FileNet BPM architecture

Process Service on the Process Engine
• Provides workflow functionality for BPM solutions
• Is a Java application that must be running for workflow activity
to occur
• Is started, stopped, and configured with Process Task
Manager (PTM)
• Includes two processes:
– PEManager
– PEServer
Process Engine
Workflow Process Service
database
PEManager
PEManager
(Queues, rosters,
event logs) PEServer
PEServer

© Copyright IBM Corporation 2011

Figure 1-30. Process Service on the Process Engine F1561.0

Notes:
Help paths
• IBM FileNet P8 Version 5.0 Information Center > Administering IBM FileNet P8 >
Working with Process Task Manager > Process Engine > Server instances > Start and
stop server instances
• IBM FileNet P8 Version 5.0 Information Center > Administering IBM FileNet P8 >
Working with Process Task Manager > Process Engine > Server instances > Configure
the Process Engine server instance
Use Process Task Manager (PTM) to start and stop the Process Service on a Process
Engine server. The Process Engine node in PTM enables you to manage the Process
Engine software (Process Service) and Process Engine servers.
The diagram on this page illustrates that PEManager and PEServer are two processes that
are included in Process Service running on the Process Engine. Process Service
communicates with the workflow database, which contains the workflow queues, rosters,
and event logs.

1-48 IBM FileNet BPM 5.0: Java API Programming © Copyright IBM Corp. 2011
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
V5.4
Student Notebook

Uempty The PEServer process handles incoming requests from the client, and runs daemon
threads and background tasks. It updates the PE database and must be shut down during
database backup.
The PEManager process handles requests to start or stop the PEServer and does not
update the database. It can be running when the database is backed up.
On a Windows machine, the Process Engine Manager process can be seen running under
Windows Services. It controls the PEManager process. The PEServer process can be
seen only by running the Process Explorer on a Linux machine. The ps command in Linux
is used to view both the PEManager and PEServer processes.

© Copyright IBM Corp. 2011 Unit 1. IBM FileNet Business Process Manager Introduction 1-49
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
Student Notebook

IBM FileNet BPM architecture

Workflow database
• A DB2, Microsoft SQL, or Oracle database that maintains
workflow data used by the Process Engine
– Also called the Process Engine database (PEDB)
• Managed and administered from Process Configuration
Console (PCC) in Workplace XT or Workplace
• Contains process regions with tables for these database
components:
– Queues
– Rosters
Process Engine
– Event Logs
Workflow Process Service
– Application Space database
PEManager
PEManager
(Queues, rosters,
– Workflows event logs) PEServer
PEServer
– Work items

© Copyright IBM Corporation 2011

Figure 1-31. Workflow database F1561.0

Notes:
Help path
• IBM FileNet P8 Version 5.0 Information Center > Integrating workflow into document
management > Process Configuration Console > Manage the workflow database
This page builds on information that you learned in the IBM FileNet P8 Prerequisite Skills
course.
The diagram illustrates that the workflow database contains queues, rosters, and logs, and
communicates with the Process Engine.

1-50 IBM FileNet BPM 5.0: Java API Programming © Copyright IBM Corp. 2011
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
V5.4
Student Notebook

Uempty
IBM FileNet BPM architecture
Component Integrator
• Service that provides communication between external
components and the Process Engine.
– Components can use Java or JMS adapters.
• Has two parts:
– Component Managers on the Application Engine make components
available to workflows.
– Component queues configured on the workflow database hold work
items waiting for service by components.

Application Engine

Workflow database Component Manager

Java JMS
JMS adaptor
adaptor
Java component
component
queue
queue

JMS
Component Manager
JMS component
component
queue
queue Java
Java adaptor
adaptor

© Copyright IBM Corporation 2011

Figure 1-32. Component Integrator F1561.0

Notes:
Help path
• IBM FileNet P8 Version 5.0 Information Center > Administering IBM FileNet P8 >
Working with Process Task Manager > Component Manager
This page introduces the Component Integrator, which makes it possible for custom Java
or Java Message Service (JMS) components (on Workplace only) available in a workflow.
Component Managers are services running on the Application Engine (AE). The Integrate
Process Components unit for solution builders covers this topic in more detail.
Component Managers can run on the Application Engine and can also run on other
servers, depending on your IBM FileNet BPM system configuration. Each Component
Manager links one or more external components with its respective component queue on
the Process Engine, as shown in the diagram. The diagram shows that Component
Managers use adapters to communicate with queues on the Process Engine.
Component Managers provide a link between the Process Engine and external systems
using a Java or JMS interface. A Component Manager coordinates one or more

© Copyright IBM Corp. 2011 Unit 1. IBM FileNet Business Process Manager Introduction 1-51
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
Student Notebook

components, which are responsible for delivering events from the Process Engine to an
external entity such as a web service or messaging system. Components are custom,
external software entities that can perform work steps. In a later lesson, you learn more
about component integration in an IBM FileNet BPM solution and about how to configure
and administer components with a Component Manager and create component queues in
the workflow database.

1-52 IBM FileNet BPM 5.0: Java API Programming © Copyright IBM Corp. 2011
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
V5.4
Student Notebook

Uempty
IBM FileNet BPM architecture
Process Task Manager (PTM)
• Tool to manage and configure process-related services
• It is used to administer the following components:
– Process Engine
– Process Simulator
– Rules Listener
– Case Analyzer
– Application Engine servers
• Each component type has one instance of PTM on the server.

© Copyright IBM Corporation 2011

Figure 1-33. Process Task Manager (PTM) F1561.0

Notes:
Help paths
• IBM FileNet P8 Version 5.0 Information Center > Administering IBM FileNet P8 >
Working with Process Task Manager
• IBM FileNet P8 Version 5.0 Information Center > Administering IBM FileNet P8 >
Working with Process Task Manager > Getting started > Start Process Task Manager
This page provides a review. More information on starting and stopping the system is
provided in the FileNet P8 Platform Administration course.
The administrator uses Process Task Manager to manage and configure process-related
services on the Process Engine, Application Engine, Process Simulator, Case Analyzer,
and Rules Listener servers.
Process Task Manager provides options for starting and stopping services, including the
Component Managers.

© Copyright IBM Corp. 2011 Unit 1. IBM FileNet Business Process Manager Introduction 1-53
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
Student Notebook

The administrator uses Process Task Manager to start the Process Service on the Process
Engine. When the Process Service starts, it starts several processes including email
notification, if configured.
To start Process Task Manager on a UNIX Process Engine, use the vwtaskman command
file located in the Process Engine software installation directory. On a Windows Process
Engine, click Start > FileNet P8 Platform > Process Engine > Process Task Manager.

1-54 IBM FileNet BPM 5.0: Java API Programming © Copyright IBM Corp. 2011
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
V5.4
Student Notebook

Uempty
IBM FileNet BPM architecture
BPM tools (Java applets)
• BPM tools are accessed from Workplace XT or Workplace by
end users and administrators.
• Process Configuration Console
– Used to configure a Process Engine workflow database and
environment
• Process Administrator
– Used to view and manage running workflows, work items, and logs
• Process Tracker
– Provides graphical view and history of a running workflow,
with options to modify participants, data fields, and groups
• Process Designer
– Used by solution designers to create workflow definitions

© Copyright IBM Corporation 2011

Figure 1-34. BPM tools (Java applets) F1561.0

Notes:
Help paths
• IBM FileNet P8 Version 5.0 Information Center > Integrating workflow into document
management > Process Configuration Console
• IBM FileNet P8 Version 5.0 Information Center > Integrating workflow into document
management > Process Administrator
• IBM FileNet P8 Version 5.0 Information Center > Integrating workflow into document
management > Process Tracker
• IBM FileNet P8 Version 5.0 Information Center > Integrating workflow into document
management > Process Designer

© Copyright IBM Corp. 2011 Unit 1. IBM FileNet Business Process Manager Introduction 1-55
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
Student Notebook

IBM FileNet BPM architecture

Process Engine farming
• All Process Engines in a farm share the database instance.
Client 1

PE #1
AE #1
BALANCER

BALANCER
LOAD

LOAD
Workflow
database
Client 2
PE #2

AE #2
PE #3

© Copyright IBM Corporation 2011

Figure 1-35. Process Engine farming F1561.0

Notes:
Help path
• IBM FileNet P8 Version 5.0 Information Center > Administering IBM FileNet P8 >
Working with Process Task Manager > Process Engine > Server instances
The Process Engine can be farmed (scaled horizontally) to support increased workload
requirements. This diagram shows an example of a Process Engine farm. A server farm is
a group of identical servers accessed through a load balancer. The load balancer might use
hardware or software technology to distribute work between server instances. All the
servers in a farm are active, provide the same set of services, and are effectively
interchangeable. The load balancer distributes incoming client requests to the servers in
the group.
All the Process Engines in a farm share the same database instance. They do not
communicate in any way, except when a workflow or configuration is transferred. At that
time, all of the machines in the farm are notified to update their configuration with
information of the newly transferred workflow. The server that receives the transfer request
(which can be any of the servers in the farm) is the server that communicates with the

1-56 IBM FileNet BPM 5.0: Java API Programming © Copyright IBM Corp. 2011
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
V5.4
Student Notebook

Uempty others. That server searches the database for the names and addresses of the other
servers and then sends them a message. Each server checks the database for a transfer in
process when the server starts running.
All servers in the Process Engine farm must have the same operating system, hardware
word size, and word boundaries, and they must have the same byte order.

© Copyright IBM Corp. 2011 Unit 1. IBM FileNet Business Process Manager Introduction 1-57
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
Student Notebook

IBM FileNet BPM architecture

Process Engine multitenancy
• Multiple PE server instances can be configured on the same
machine using different workflow databases.
• Limitations
– Multiple server instances cannot be on the same machine using the
same workflow database.
– A PE virtual server can have only one workflow database.
Database
Machine A Machine B instances
PEManager
PEManager PEManager
PEManager
Client PEDB1
PE
PE virt
virt serv
serv 11 PE
PE virt
virt serv
serv 11

PE
PE virt
virt serv
serv 22 PE
PE virt
virt serv
serv 22 PEDB2
AE

© Copyright IBM Corporation 2011

Figure 1-36. Process Engine multitenancy F1561.0

Notes:
Reference
• IBM FileNet P8 System Overview, V5.0
(http://www-05.ibm.com/e-business/linkweb/publications/servlet/pbi.wss?CTY=US&FN
C=SRX&PBL=SC19-3237-00)
In a single-machine, stand-alone deployment of Process Engine, the Process Engine
software is installed one time on a server and is configured to use a specific workflow
database.
In a distributed installation scenario, a Process Engine installation can consist of a virtual
server with multiple server instances across multiple machines. A Process Engine server
instance is a single, multithreaded process that handles incoming requests from clients of
the Process Engine. The server instance reads and writes to the Process Engine database
in response to the client requests.

1-58 IBM FileNet BPM 5.0: Java API Programming © Copyright IBM Corp. 2011
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
V5.4
Student Notebook

Uempty Diagram
The diagram on this page shows one possible configuration in which multiple PE virtual
servers are located on multiple machines. Both Machine A and Machine B contain
instances of PE virtual server 1 (PE virt serv 1) and PE virtual server 2 (PE virt serv 2).
Each virtual server set (for example, PE virt serv 1 on Machine A and PE virt serv 1 on
Machine B) reads and writes to its own Process Engine database instance (for example,
PEDB1).
Important: To avoid unexpected consequences in an environment with multiple Process
Engine servers, always include the virtual server name as an argument when starting all
command-line server tools (for example, vwtool, vwlog, and vwtaskman) to identify which
virtual server you want to act on. If the virtual server name is not explicitly identified, the
tool operates on the default virtual server. More information about Process Engine server
tools is covered in other units in this course.
Process Task Manager and virtual servers
Process Task Manager running on the Process Engine allows you to manage and
configure options of the Process Engine software. You can manage a single Process
Engine virtual server at a time through Process Task Manager. The Instances node
displays the names of all Process Engine server instances and load balancers in a farmed
Process Engine system.

© Copyright IBM Corp. 2011 Unit 1. IBM FileNet Business Process Manager Introduction 1-59
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
Student Notebook

IBM FileNet BPM architecture

Architecture overview of IBM FileNet BPM

© Copyright IBM Corporation 2011

Figure 1-37. Architecture overview of IBM FileNet BPM F1561.0

Notes:
Reference
• IBM FileNet P8 System Overview, V5.0
(http://www-05.ibm.com/e-business/linkweb/publications/servlet/pbi.wss?CTY=US&FN
C=SRX&PBL=SC19-3237-00, see FileNet P8 core components > Process Engine.)
The diagram on this page illustrates the major components of an IBM FileNet BPM system.
The diagram indicates which components communicate with other components in the
system. This diagram is not intended to show all possible components or configurations.
For more information, see the system overview reference given on this page.
Notice the following key points of the IBM FileNet BPM architecture:
• Process Service on Process Engine – The core of the business process management
system. It provides workflow services on behalf of Process Engine. The Process
Service is composed of the PEServer and PEManager processes.
• Workflow database – Contains Process Engine configuration information, as well as
running instances of workflows.

1-60 IBM FileNet BPM 5.0: Java API Programming © Copyright IBM Corp. 2011
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
V5.4
Student Notebook

Uempty • Component Integrator on the Application Engine server or other servers – Used to
manage integration with external Java and JMS components. Component Integrator
allows you to configure one or more Component Managers to communicate with
external components needed in a workflow application.
• Process Task Manager – Provides administrative tools for configuring and managing
process-related services on the Process Engine server and other process-related
servers.
• Workflow auto-launch – A component that launches workflows in the Process Engine
system. You can configure this component to launch a specific workflow in response to
specific events. For example, filing a document in a folder might launch a review
process in the Process Engine system.
• Email Notification – Enables automatic transmission of email to users when specified
process-related events occur.
• Directory Services – Directory service functionality is accessed through Content
Engine, which supports several LDAP providers and single-sign-on (SSO) functionality.
• Process Java API provides programmatic access to the runtime, administration,
configuration, and workflow functionality supported in Process Engine.

© Copyright IBM Corp. 2011 Unit 1. IBM FileNet Business Process Manager Introduction 1-61
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
Student Notebook

IBM FileNet BPM architecture

Activities
In your Student Exercises
• Unit: IBM FileNet Business Process Manager
Introduction
• Lesson: IBM FileNet BPM architecture
• Activities:
– Identify functions of IBM FileNet BPM components.
– View workflow database information.

© Copyright IBM Corporation 2011

Figure 1-38. Activities F1561.0

Notes:
Use your Student Exercises to perform the activities listed.

1-62 IBM FileNet BPM 5.0: Java API Programming © Copyright IBM Corp. 2011
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
V5.4
Student Notebook

Uempty Unit 2. Process Engine Java API Overview

What this unit is about

This unit describes the concepts of writing Java code for interfacing
with the Process Engine. This unit gives an overview of the Process
Engine objects.

What you should be able to do

After completing this unit, you should be able to:
• Locate the Process Engine developer help documents.
• Locate the Process Java API Reference that contains Process
Engine Java API classes.
• Set up the Eclipse environment.

How you will check your progress

• Successfully complete the activities in the Student Exercises book.

References
www.ibm.com/support/documentation/us/en (Support & downloads
page)
Note: IBM FileNet products belong to the Information Management
product set.

© Copyright IBM Corp. 2011 Unit 2. Process Engine Java API Overview 2-1
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
Student Notebook

Process Engine Java API Overview

Unit lessons
This unit contains the following lessons:
• Process Engine Java API concepts
• Process Engine objects

© Copyright IBM Corporation 2011

Figure 2-1. Unit lessons F1561.0

Notes:
Lessons in this unit
This unit has two lessons. After the first lesson, each lesson relies on information and skills
taught in the prior lessons. For best results, do these lessons in the sequence presented.
Process Engine Java API concepts – In this lesson, you get an overview of the concepts
of writing Java code for interfacing with the Process Engine.
Process Engine objects – In this lesson, you get an orientation to the Process Engine
objects.

2-2 IBM FileNet BPM 5.0: Java API Programming © Copyright IBM Corp. 2011
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
V5.4
Student Notebook

Uempty Lesson 2.1. Process Engine Java API concepts

© Copyright IBM Corp. 2011 Unit 2. Process Engine Java API Overview 2-3
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
Student Notebook

Lesson:
Process Engine Java API concepts
• Why is this lesson important to you?
– Your company has purchased an IBM FileNet P8 system and plans to
manage their processes using the IBM FileNet P8 Process Engine. As
their programmer, you want an orientation to the IBM FileNet P8
Process Java API, which you are going to use to write a custom
application for the company.

© Copyright IBM Corporation 2011

Figure 2-2. Lesson: Process Engine Java API concepts F1561.0

Notes:

2-4 IBM FileNet BPM 5.0: Java API Programming © Copyright IBM Corp. 2011
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
V5.4
Student Notebook

Uempty
Process Engine Java API concepts
Activities that you need to complete
• Locate the Process Engine developer help documents.
• Locate the Process Java API Reference that contains
Process Engine Java API classes.

© Copyright IBM Corporation 2011

Figure 2-3. Activities that you need to complete F1561.0

Notes:
These are the activities that you are going to perform in this lesson.

© Copyright IBM Corp. 2011 Unit 2. Process Engine Java API Overview 2-5
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
Student Notebook

Process Engine Java API concepts

Process API package

Database Objects
Work Objects
Workflow Definition
Security Objects
Objects

Runtime API Workflow

Administration API Definition API

Classes Classes

Package: filenet.vw.api

= The Runtime API is the focus of this course.

© Copyright IBM Corporation 2011

Figure 2-4. Process API package F1561.0

Notes:
Help path
• IBM FileNet P8 Version 5.0 Information Center > Developing IBM FileNet P8
applications > Process Engine Development > Process Java Developer's Guide >
Developing Process Applications > Process API Class Calling Sequences
The diagram shows the three functional groups in the Process Engine API package:
• Runtime API
• Administration and configuration API
• Workflow definition API
The Runtime API and the Administration and Configuration API expose the database
objects, work objects, and security objects.
The Workflow Definition API exposes the workflow definition objects.
This course focuses on the Runtime API.

2-6 IBM FileNet BPM 5.0: Java API Programming © Copyright IBM Corp. 2011
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
V5.4
Student Notebook

Uempty
Process Engine Java API concepts
Process API naming conventions - objects

VWSomeObjectName

fetchMethod() getMethod() setMethod() isMethod() doMethod() convertMethod()

(usually)
VWResultObject Java object Boolean void varies
void

• Process Engine objects

– “VW” + ObjectName
– “VWObjectName” + “Element”
– “VWObjectName” + “Definition”
– “VWObjectName” + “Type”

© Copyright IBM Corporation 2011

Figure 2-5. Process API naming conventions - objects F1561.0

Notes:

© Copyright IBM Corp. 2011 Unit 2. Process Engine Java API Overview 2-7
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
Student Notebook

Process Engine Java API concepts

Process API naming conventions - methods

createMethod() setMethod() doMethod()

fetchMethod() getMethod() isMethod() convertMethod()

(usually)
VWResultObject Java object Boolean void varies
void

• Object methods
– fetchMethod() – setMethod()
• Retrieves object from VWService • Sets Parameter value
• Requires database operation – isMethod()
– getMethod() • Tests presence of state
• Retrieves parameter – doMethod()
• Usually no database operation • Processes work on VWService
(gets from cache) • Usually void method
– createMethod() – convertMethod()
• Instantiates a VW object • Retrieves one object parameter
• Often retrieves parameter from corresponding to another one
region database

© Copyright IBM Corporation 2011

Figure 2-6. Process API naming conventions - methods F1561.0

Notes:
The diagram shows the naming conventions for the Process API methods:
fetchMethod()
Retrieves object from VWService
Requires database operation
getMethod()
Retrieves parameter
Usually no database operation (gets from cache)
createMethod()
Instantiates a VW object
Often retrieves parameter from region database
setMethod()
Sets Parameter value

2-8 IBM FileNet BPM 5.0: Java API Programming © Copyright IBM Corp. 2011
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
V5.4
Student Notebook

Uempty isMethod()
Tests presence of state
doMethod()
Processes work on VWService
Usually void method
convertMethod()
Retrieves one object parameter corresponding to another one

© Copyright IBM Corp. 2011 Unit 2. Process Engine Java API Overview 2-9
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
Student Notebook

Process Engine Java API concepts

Primary API classes

VWSession VWWorkflowDefinition

VWQueue VWSystemConfiguration VWStepDefinition

VWRoster VWSystemAdministration VWMapDefinition

VWLog VWUserInfo VWFieldDefinition

VWWorkObject VWSecurityList

Administration
and Workflow
Runtime Configuration definition

© Copyright IBM Corporation 2011

Figure 2-7. Primary API classes F1561.0

Notes:
The diagram shows the primary API classes under each of the three functional groups in
the Process Engine API package:
• Runtime API
• Administration and configuration API
• Workflow definition API
The Runtime API exposes the following objects:
• VWSession
• VWQueue
• VWRoster
• VWLog
• VWWorkObject
The Administration and Configuration API exposes the following objects:

2-10 IBM FileNet BPM 5.0: Java API Programming © Copyright IBM Corp. 2011
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
V5.4
Student Notebook

Uempty • VWSession
• VWSystemConfiguration
• VWSystemAdministration
• VWUserInfo
• VWSecurityList
The Workflow Definition API exposes the following objects:
• VWWorkflowDefinition
• VWStepDefinition
• VWMapDefinition
• VWFieldDefinition

© Copyright IBM Corp. 2011 Unit 2. Process Engine Java API Overview 2-11
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
Student Notebook

Process Engine Java API concepts

Process development environment and samples
• IBM FileNet P8 BPM includes a Process Development
Environment for developers
– Process Engine Java API runtime classes
• See the “Required Java Archive (JAR) files” page in this lesson.
• Samples
– On the FileNet P8 Documentation CD
– …\ecm_help\developer_help\process_java_api\Developer
Files\samples folder contains the following:
• API: sample Java API files that can be used to create, launch, complete,
display, and save log information for a workflow
• vwpanel: sample Java Step Processor application files

© Copyright IBM Corporation 2011

Figure 2-8. Process development environment and samples F1561.0

Notes:
Help path
• IBM FileNet P8 Version 5.0 Information Center > Developing IBM FileNet P8
applications > Process Engine Development > Process Java Developer's Guide >
Developing Process Applications > Process API Samples Overview

2-12 IBM FileNet BPM 5.0: Java API Programming © Copyright IBM Corp. 2011
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
V5.4
Student Notebook

Uempty
Process Engine Java API concepts
Required Java Archive (JAR) files

JAR File Name Description

Contains the Process Engine Java API runtime

pe.jar classes. This JAR file is located on the Application
Engine.

Contains third-party classes used by the Process

pe3pt.jar Engine. Located on the Application Engine.

Contains the core JAR file for the Content Engine Java
Jace.jar
API.

An application
If already in an application server, this JAR file is not
server-specific
required, except in a stand-alone JVM.
JAR file

© Copyright IBM Corporation 2011

Figure 2-9. Required Java Archive (JAR) files F1561.0

Notes:
Help path
• IBM FileNet P8 Version 5.0 Information Center > Developing IBM FileNet P8
applications > Process Engine Development > Process Java Developer's Guide >
Configuring the Process Development Environment
Both the Process Engine Java API and the Content Engine Java API must be present on
the client machine (the Content Engine setup program installs both the Process Engine
Java API and the Content Engine Java API components). The Content Engine Java API is
configured to work over the EJB transport.
The JAR files necessary for Process application development are installed on either the
Application Engine or Process Engine host.
This course focuses on the pe.jar file.

© Copyright IBM Corp. 2011 Unit 2. Process Engine Java API Overview 2-13
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
Student Notebook

Process Engine Java API concepts

Configuring the Java runtime environment
• Install the appropriate JDK
– For the latest information on JDKs supported, go to
http://www-306.ibm.com/software/data/cm
– Use the Search menu to select the FileNet P8 solutions.
• Steps to configure
1. Create a local directory (Example: …\pe).
2. Copy the sample files from the FileNet P8 Platform Installation CD to the
new \pe directory.
3. Add pe.jar and other required .jar files to the classpath using one of the
following methods:
• The javac.exe and java.exe command line
• A script or a batch file
• An Integrated Development Environment (IDE)
Do not add the .jar files to the CLASSPATH environment variable.

© Copyright IBM Corporation 2011

Figure 2-10. Configuring the Java runtime environment F1561.0

Notes:
Help path
• IBM FileNet P8 Version 5.0 Information Center > Developing IBM FileNet P8
applications > Process Engine Development > Process Java Developer's Guide >
Configuring the Process Development Environment
Issues with adding JAR files to the classpath:
The addition of the pe.jar and other .jar files to the system classpath can cause security
conflicts if you attempt to run the built-in Java client applications on your development
system.
The conflict is caused when, for example, the Process Engine server sends the correct
path for the pw.jar, but the classpath statement forces the client application to use the
pw.jar file from the specified location.

2-14 IBM FileNet BPM 5.0: Java API Programming © Copyright IBM Corp. 2011
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
V5.4
Student Notebook

Uempty If you run the Java Plugin console on a system on which you are attempting to run the
built-in Java client application with the pw.jar or pe.jar files specified in the classpath, you
receive exceptions similar to the following:
java.security.AccessControlException: access denied
(java.lang.RuntimePermission modifyThreadGroup)
Use any one of the following workarounds to correct this behavior:
1. Create a script that includes a classpath variable that specifies the locations of the
pw.jar or pe.jar files.
2. Use an IDE to compile and run your applications. In this case, you can specify the
classpath locations specific to your project (or the global project setting).
3. Specify the locations of the pw.jar or pe.jar files in the command line you use to compile
and run an application.
The instructions in the Student Exercises use workarounds 1 and 2.

© Copyright IBM Corp. 2011 Unit 2. Process Engine Java API Overview 2-15
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
Student Notebook

Process Engine Java API concepts

Activities

Explore
Explore the
the Java
Java API
API documentation.
documentation.
•• Use
Use the
the help
help paths
paths listed
listed in
in the
the notes
notes to
to do
do the
the
following:
following:
–– Locate
Locatethe
theProcess
ProcessEngine
Enginedeveloper
developerhelp
helpdocuments.
documents.
–– Locate
Locatethe
theProcess
ProcessJava
JavaAPI
APIReference
Referencethat
thatcontains
contains
Process Engine Java API classes.
Process Engine Java API classes.

© Copyright IBM Corporation 2011

Figure 2-11. Activities F1561.0

Notes:
Help paths
• IBM FileNet P8 Version 5.0 Information Center > Developing IBM FileNet P8
applications > Process Engine Development > Process Java Developer's Guide >
Introduction to Process Applications
• IBM FileNet P8 Version 5.0 Information Center > Developing IBM FileNet P8
applications > Process Engine Development > Process Java API Reference

2-16 IBM FileNet BPM 5.0: Java API Programming © Copyright IBM Corp. 2011
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
V5.4
Student Notebook

Uempty Lesson 2.2. Process Engine objects

© Copyright IBM Corp. 2011 Unit 2. Process Engine Java API Overview 2-17
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
Student Notebook

Lesson:
Process Engine objects
• Why is this lesson important to you?
– Your company has purchased an IBM FileNet P8 system
and plans to manage their processes using the IBM
FileNet P8 Process Engine. You want an orientation to
the Process Engine objects, which you are going to use
to write a custom application for the company.

© Copyright IBM Corporation 2011

Figure 2-12. Lesson: Process Engine objects F1561.0

Notes:

2-18 IBM FileNet BPM 5.0: Java API Programming © Copyright IBM Corp. 2011
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
V5.4
Student Notebook

Uempty
Process Engine objects
Activities that you need to complete
• Set up the Eclipse environment.

© Copyright IBM Corporation 2011

Figure 2-13. Activities that you need to complete F1561.0

Notes:
These are the activities that you are going to perform in this lesson.

© Copyright IBM Corp. 2011 Unit 2. Process Engine Java API Overview 2-19
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
Student Notebook

Process Engine objects

Runtime objects
• Primary purpose
– Perform workflow operations
• Primary objects involved
– VWSession
– Database Objects
• VWRoster
• VWQueue
• VWLog
– Work Elements
• VWWorkObject
• VWRosterElement
• VWQueueElement
• VWStepElement
• VWLogElement
© Copyright IBM Corporation 2011

Figure 2-14. Runtime objects F1561.0

Notes:

2-20 IBM FileNet BPM 5.0: Java API Programming © Copyright IBM Corp. 2011
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
V5.4
Student Notebook

Uempty
Process Engine objects
Database objects – typical isolated region

Queue Roster
classes
classes
System
queues Roster
Runtime classes read
User User-defined and modify contents
queues User-defined
rosters Administration and
work queues
Configuration classes
read and modify
structure

Log
User-defined
logs
Log
Statistics log
Statistics Log
classes classes

© Copyright IBM Corporation 2011

Figure 2-15. Database objects - typical isolated region F1561.0

Notes:
The diagram shows the database objects in a typical isolated region.
Roster
A workflow roster is a table in a database that stores the current location of and other
information about all workflows. Workflow rosters provide the Process Engine with an
efficient way to locate specific workflows and work items.
Queue
A queue contains each individual work item in a table that is waiting to be processed. Each
entry in the roster has a corresponding entry in a queue. The API can retrieve and modify
work items in work queues and user queues.
Event Log
Event logs are also tables in the database and contain a record of specific system- or
workflow-related events for each isolated region. This type of logging is useful for tracking
workflow activity. Each event that is logged is part of an event category and has an
associated event number.

© Copyright IBM Corp. 2011 Unit 2. Process Engine Java API Overview 2-21
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
Student Notebook

Statistics Tables
Statistics for region activity are maintained in two tables for each isolated region on a
server.
RDBMS
The objects listed above are stored as tables in a RDBMS. In addition, a set of views has
been created to enable direct database access from a custom program.
Attention: When the RDBMS is accessed directly, it must be for viewing information in a
read-only manner. Any modification of table data without using the provided APIs or
applications is not supported.
Do not modify, delete, append to, or create additional tables in the RDBMS. Any
modification of the tables, views, or other database items created by the Process Engine
without using the provided APIs or applications is not supported.

2-22 IBM FileNet BPM 5.0: Java API Programming © Copyright IBM Corp. 2011
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
V5.4
Student Notebook

Uempty
Process Engine objects
Work elements
• Interpretation of an item (row) in a database object
•Roster element
Roster •Work object

Queue •Queue element

•Step element
•Instruction element
RDBMS
Table Record =
1 Work Item
Log •Log element

© Copyright IBM Corporation 2011

Figure 2-16. Work elements F1561.0

Notes:
The diagram shows the work elements. Each item in a table is used as a work element.
Work elements are of six types as shown below. The items in a roster can be of two of
these types and items in a queue can be of four of these types. Event log items can be
retrieved only in one type. The only common type is the Work Object, which is available
from both queues and rosters.
Roster and queue elements are created from the exposed fields in a table. Each roster or
queue element represents a work item in the queue or roster. To retrieve the unexposed
fields, the work item from the queue or roster must be retrieved as a work object, a step
element, or an instruction element.
A step element represents a work item in a queue. When accessing an element for a step,
the data for the work item is retrieved from the BLOB. The step parameters are then
retrieved and sent to the step processor running on the client.
One system column in queue tables, F_WorkObjectBlob, is the binary large object (BLOB)
that contains all of the unexposed fields of the work item. Unexposed fields are removed
from this object.

© Copyright IBM Corp. 2011 Unit 2. Process Engine Java API Overview 2-23
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
Student Notebook

Process Engine objects

Work object access
• A work object can be retrieved from VWWorkObject
a roster or queue work item.
Step Description
– Enables access to most information
Originator
associated with its workflow.
Responses
– Information is retrieved from several
sources. Participants
Step Parameters
Exposed User Fields
Exposed System Fields

Unexposed Fields (BLOB)

As data is exposed, it is
removed from the BLOB

© Copyright IBM Corporation 2011

Figure 2-17. Work object access F1561.0

Notes:

2-24 IBM FileNet BPM 5.0: Java API Programming © Copyright IBM Corp. 2011
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
V5.4
Student Notebook

Uempty
Process Engine objects
Work element access
VWWorkObject

Step description
Originator VWStepElement
Responses
Participants
Step parameters
Exposed User Fields
VWQueueElement Exposed system fields
Unexposed fields (BLOB)

VWRosterElement

Reference to work object

Roster exposed fields

© Copyright IBM Corporation 2011

Figure 2-18. Work element access F1561.0

Notes:
The diagram shows the exposed fields in the work elements.
The runtime API exposes elements that contain different interpretations of a work item in
five different classes. The resource demands to recover an element increase as the
amount of interpretation contained in an element increases. VWRosterElement
This work element returns all of the exposed fields on the roster. Note that each roster
maintains its own list of exposed fields.
VWQueueElement
This work element returns all of the exposed fields on the queue. Note that each queue
maintains its own list of exposed fields.
VWStepElement
This work element is used primarily for processing a work item on a step. This element
provides access to the information needed to process a step. This information includes the
step definition and the parameters defined on the current step, including and enforces their

© Copyright IBM Corp. 2011 Unit 2. Process Engine Java API Overview 2-25
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
Student Notebook

mode (read or write ability). Step parameters can be exposed or unexposed fields. Fields
other than the parameters of the current step are not accessible from a VWStepElement.
Specific functions in the VWStepElement class, some of which are not directly available in
a VWWorkObject, are designed to help in the processing of a work item.
VWWorkObject
This work element is used primarily for administrative purposes. This work element
provides access to all of the data in the work item. Work items can also be processed from
this item.
VWInstructionElement
This work element is a legacy object from other FileNet applications. Its use is discouraged.

2-26 IBM FileNet BPM 5.0: Java API Programming © Copyright IBM Corp. 2011
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
V5.4
Student Notebook

Uempty
Process Engine objects
Work class objects
Runtime classes launch and
Step classes Workflow classes process work objects
(Runtime) (Workflow definition) Workflow definition classes create
and transfer workflow definitions

vwtool lists last

transferred version

RDBMS lists all

transferred versions
© Copyright IBM Corporation 2011

Figure 2-19. Work class objects F1561.0

Notes:
Workflow definitions and work classes
A workflow definition object is the basis of a work class. A workflow definition file that is
transferred to the isolated region becomes a work class. If the workflow is transferred
several times, for example after several revisions are made, multiple work classes are
created on the server.
Each work class on the region has a unique numerical identification visible only at the
server administration level. This numerical value is stored in the VW Version property of the
Workflow Definition document in the Content Engine Object Store. A work class must also
have a workflow name. The workflow name is an important element of the work class, and
it is the most frequent component used to launch a workflow instance from a work class.
The work class is a template on the isolated region that describes the attributes of a work
item, such as data fields, a security configuration, and event logging options.

© Copyright IBM Corp. 2011 Unit 2. Process Engine Java API Overview 2-27
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
Student Notebook

Work items and work classes

All work items belong to a work class and are registered with a designated roster for that
work class. Work items belonging to the same work class have the same attributes. Work
classes also contain process maps to specify the processing for work items belonging to
the class.

2-28 IBM FileNet BPM 5.0: Java API Programming © Copyright IBM Corp. 2011
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
V5.4
Student Notebook

Uempty
Process Engine objects
Administration and configuration objects
• Primary purposes
– Establish session
– Manage users and system configuration
– Functionality of the Configuration Console (configuring an Isolated Region)
• Primary objects involved
– VWSession
– Security objects
– VWUserInfo
– VWSecurityList
– VWSystemConfiguration
– VWRosterDefinition
– VWQueueDefinition
– VWLogDefinition

© Copyright IBM Corporation 2011

Figure 2-20. Administration and configuration objects F1561.0

Notes:

© Copyright IBM Corp. 2011 Unit 2. Process Engine Java API Overview 2-29
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
Student Notebook

Process Engine objects

Security objects
• The Process Engine relies on
the Content Engine for
authentication and directory
service access operations
• The Process Engine API does
not create or modify the IBM
FileNet P8 Authentication
Provider user information.
• The Process Engine API can
read and modify the Task
Settings.

© Copyright IBM Corporation 2011

Figure 2-21. Security objects F1561.0

Notes:
The diagram shows the User Preferences settings page for the Tasks in Workplace XT.
Before a user can participate in a process workflow, the user must be logged on as a valid
user. The Process Engine API can be used to modify Process Engine-specific user
parameters, such as email address and out-of-office status, but it cannot be used to add or
delete users and groups, or modify core security information, such as a name, a group
affiliation, or a password.
Workflow groups are not part of the IBM FileNet P8 Authentication Provider database. A
workflow group is a workflow definition parameter for manipulating groups of security
objects.

2-30 IBM FileNet BPM 5.0: Java API Programming © Copyright IBM Corp. 2011
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
V5.4
Student Notebook

Uempty
Process Engine objects
Workflow definition objects
• Primary purpose
– Create and modify workflow definitions
– Functionality of the Process Designer
• Primary objects involved
– VWWorkflowDefinition
• VWStepDefinition
• VWMapNode (abstract class)
• VWMapDefinition
• VWFieldDefinition
• VWInstructionDefinition (abstract class)

© Copyright IBM Corporation 2011

Figure 2-22. Workflow definition objects F1561.0

Notes:

© Copyright IBM Corp. 2011 Unit 2. Process Engine Java API Overview 2-31
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
Student Notebook

Process Engine objects

Using Eclipse IDE for writing your code
• You can use Eclipse or Notepad and the Windows
Command Prompt to write and execute your code.
• Your Student Exercises book include instructions for the
following:
– Setting up a project in Eclipse
– Writing code using a text editor
– Compiling and executing the code in Command Prompt

© Copyright IBM Corporation 2011

Figure 2-23. Using Eclipse IDE for writing your code F1561.0

Notes:

2-32 IBM FileNet BPM 5.0: Java API Programming © Copyright IBM Corp. 2011
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
V5.4
Student Notebook

Uempty
Process Engine objects
Demonstrations
• Set up the Eclipse environment.
– Create an Eclipse project.
– Add library files.
– Create a package.
– Create a Java file.
– Set VM arguments and execute the code.

© Copyright IBM Corporation 2011

Figure 2-24. Demonstrations F1561.0

Notes:
Demonstration notes
1. Start Eclipse by double-clicking the icon on the desktop.
2. Follow the instructions in the "Set Up Eclipse IDE" lesson in your Student Exercises to
complete each task.

© Copyright IBM Corp. 2011 Unit 2. Process Engine Java API Overview 2-33
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
Student Notebook

Process Engine objects

Activities

In
In your
your Student
Student Exercises
Exercises book
book
•• Unit:
Unit: Set
Set Up
Up Eclipse
Eclipse IDE
IDE
•• Lesson:
Lesson: Set
Set Up
Up Eclipse
Eclipse IDE
IDE
•• Activities
Activities
–– Set
Setup
upthe
theEclipse
Eclipseenvironment.
environment.

© Copyright IBM Corporation 2011

Figure 2-25. Activities F1561.0

Notes:
Use your Student Exercises book to perform the activities listed.

2-34 IBM FileNet BPM 5.0: Java API Programming © Copyright IBM Corp. 2011
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
V5.4
Student Notebook

Uempty Unit 3. Log On to the Process Engine

What this unit is about

This unit describes how to write code using Process Engine Java API
to do the following:
Log on to and log out off the Process Engine
Catch any VWExceptions thrown and display the associated message
Retrieve current user information,Process Engine user names and
group names

What you should be able to do

After completing this unit, you should be able to:
• Create a Process Engine session.
• Handle a VWException.
• Retrieve user and group information.

How you will check your progress

• Successfully complete the activities in the Student Exercises book.

References
www.ibm.com/support/documentation/us/en (Support & downloads
page)
Note: IBM FileNet products belong to the Information Management
product set.

© Copyright IBM Corp. 2011 Unit 3. Log On to the Process Engine 3-1
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
Student Notebook

Log On to the Process Engine

Unit lessons
This unit contains the following lessons:
• Create a Process Engine session
• Handle exceptions
• Retrieve user and group information

© Copyright IBM Corporation 2011

Figure 3-1. Unit lessons F1561.0

Notes:
Lessons in this unit
This unit has three lessons. After the first lesson, each lesson relies on information and
skills taught in the prior lessons. For best results, do these lessons in the sequence
presented.
Create a Process Engine session – In this lesson, you write code to log on to and log off
from the Process Engine.
Handle exceptions – In this lesson, you write code to catch any VWExceptions thrown
and display the associated message.
Retrieve user and group information – In this lesson, you write code to retrieve current
user information, and Process Engine user names and group names

3-2 IBM FileNet BPM 5.0: Java API Programming © Copyright IBM Corp. 2011
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
V5.4
Student Notebook

Uempty Lesson 3.1. Create a Process Engine session

© Copyright IBM Corp. 2011 Unit 3. Log On to the Process Engine 3-3
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
Student Notebook

Lesson:
Create a Process Engine session
• Why is this lesson important to you?
– Your company manages its business processes using the IBM
FileNet Business Process Manager. As their programmer, you are
going to write code to log on to the Process Engine to access the
server.

© Copyright IBM Corporation 2011

Figure 3-2. Lesson: Create a Process Engine session F1561.0

Notes:

3-4 IBM FileNet BPM 5.0: Java API Programming © Copyright IBM Corp. 2011
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
V5.4
Student Notebook

Uempty
Create a Process Engine session
Activities that you need to complete

• Create a Process Engine session.

© Copyright IBM Corporation 2011

Figure 3-3. Activities that you need to complete F1561.0

Notes:
These are the activities that you are going to perform in this lesson.

© Copyright IBM Corp. 2011 Unit 3. Log On to the Process Engine 3-5
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
Student Notebook

Create a Process Engine session

Connection points
• A setting that identifies a specific isolated region and PE server
– Used to communicate workflow requests from the Application Engine or
Content Engine to the Process Engine Process Service

• A connection point is configured on the Content Engine

– Set in Workplace Site Preferences for Workplace clients
– Used by the Application Engine, Content Engine, and Process Engine
engines

Content
Process
Engine
Engine
Application
Workplace Enterprise
Manager Engine Process
Client Service
Connection
Point
Component
Managers

© Copyright IBM Corporation 2011

Figure 3-4. Connection points F1561.0

Notes:
Help path
• IBM FileNet P8 Version 5.0 Information Center > Integrating workflow into document
management > Process applications concepts > Administration and configuration >
About connection points
A connection point name identifies a specific isolated region in the workflow database. An
administrator defines the isolated region (Process Engine server, communications port,
isolated region number) and specifies the connection point name in Enterprise Manager. To
specify the isolated region that is used by all Workplace applications for Process-related
functionality, an administrator sets the connection point in Workplace Site Preferences.
The Application Engine sends the client request to the appropriate engine. The Content
Engine connection point is used to communicate requests to the Process Engine Process
Service. In addition to the process-related Workplace applications, the following
applications also require a connection point to communicate to the Process Engine:
Component Managers, Process Analyzer, Process Engine Web Services.

3-6 IBM FileNet BPM 5.0: Java API Programming © Copyright IBM Corp. 2011
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
V5.4
Student Notebook

Uempty
Create a Process Engine session
Connection point function and usage
• Connection points
–Connect the Process Engine API to an associated isolated region.
–Replace the router process used in previous Process Engine
releases.
• Create and manage the connection points using
–The FileNet Enterprise Manager user interface of the Content Engine
• To establish a Process Engine session
–A connection point must be specified.
–The Content Engine host must be accessible.
–The Content Engine host Universal Resource Indicator (URI) must be
set.

© Copyright IBM Corporation 2011

Figure 3-5. Connection point function and usage F1561.0

Notes:
Help paths
• IBM FileNet P8 Version 5.0 Information Center > Developing IBM FileNet P8
applications > Process Engine Development > Process Java Developer's Guide >
Connection Points
• IBM FileNet P8 Version 5.0 Information Center > Administering IBM FileNet P8 >
Administering Content Engine > Connection points > Concepts
Connection points:
• Defined in the Content Engine API using the following classes: PEConnectionPoint,
IsolatedRegion
• Persisted in the Global Configuration Data (GCD) on the Content Engine.
• Reflected in the Domain.PEConnectionPoints property of the Content Engine.
Multiple connection points can reference the same isolated region.

© Copyright IBM Corp. 2011 Unit 3. Log On to the Process Engine 3-7
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
Student Notebook

What is Global Configuration Data (GCD)?

The Global Configuration Data (GCD) is initialized or created by the server on which a
FileNet P8 domain is first created. GCD is the heart of the FileNet P8 domain. The GCD is
a hierarchical representation of the IBM FileNet P8 domain. The GCD is stored in a
database and contains information about all the Content Engine components installed into
the FileNet P8 domain.

3-8 IBM FileNet BPM 5.0: Java API Programming © Copyright IBM Corp. 2011
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
V5.4
Student Notebook

Uempty
Create a Process Engine session
Setting the Content Engine URI
• The Content Engine host URI must be set prior to creating or
logging on to a session
• Three ways to specify the Content Engine URI
1.Call VWSession.setBootstrapCEURI to specify the URI as a String.
2.Specify the reference address in the value of the
filenet.pe.bootstrap.ceuri system property.
3.Call VWSession.setBootstrapConfiguration to specify the URI as an
InputStream.

© Copyright IBM Corporation 2011

Figure 3-6. Setting the Content Engine URI F1561.0

Notes:
Help path
• IBM FileNet P8 Version 5.0 Information Center > Developing IBM FileNet P8
applications > Process Engine Development > Process Java Developer's Guide >
Connection Points
The following method is used in the student exercises:
Specify in the value of the system property: filenet.pe.bootstrap.ceuri
Example: Start your application with the -D JVM parameter
-Dfilenet.pe.bootstrap.ceuri=http://ccv01135:9080/wsi/FNCEWS40MTOM/
Another way to provide this information is to call the following methods in your code:
System.setProperty("java.security.auth.login.config", "C:\\Program
Files\\IBM\\FileNet\\CEClient\\config\\samples\\jaas.conf.WSI");
System.setProperty("filenet.pe.bootstrap.ceuri",
"http://ccv01135:9080/wsi/FNCEWS40MTOM/");

© Copyright IBM Corp. 2011 Unit 3. Log On to the Process Engine 3-9
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
Student Notebook

Create a Process Engine session

System dependency for the Process Engine
• Process Engine relies on Content Engine for authentication
and directory service access operations
• Without a Content Engine server, the Process Engine server
–Can start
–Displays errors until the Content Engine is available
–Cannot process work items
–Cannot refresh user and group information
• If the Process Engine server is already running
– It continues to run successfully until it needs to refresh its user
cache.

© Copyright IBM Corporation 2011

Figure 3-7. System dependency for the Process Engine F1561.0

Notes:

3-10 IBM FileNet BPM 5.0: Java API Programming © Copyright IBM Corp. 2011
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
V5.4
Student Notebook

Uempty
Create a Process Engine session
Authenticating the PE Java API client using CE

© Copyright IBM Corporation 2011

Figure 3-8. Authenticating the PE Java API client using CE F1561.0

Notes:
Help path
• IBM FileNet P8 Version 5.0 Information Center > Security > IBM FileNet P8 security >
Authentication > Process Engine authentication
Authenticating the Process Engine (PE) Java API client using Content Engine (CE)
EJB transport
The PE client first authenticates with JAAS on the application server and then
authenticates with the CE server. The following steps occur as the PE client application
initializes and then makes a call to the PE server:
1. The PE client performs a JAAS login, using the Login Module configured in the client
environment.
2. The PE Application makes a call to the PE Java API.
3. The PE Java API makes a call to the CE Java API to get a FileNet P8 identity token for
authentication.

© Copyright IBM Corp. 2011 Unit 3. Log On to the Process Engine 3-11
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
Student Notebook

4. The CE Java API makes a call to the server. At the CE server, the call arrives at the
J2EE application server EJB container with the caller's JAAS Subject. The application
server examines its security policy configuration.
5. If the incoming JAAS Subject is validated by the application server, the call is passed
through to the CE EJB, and the JAAS Subject is available to the CE EJB.
6. Within the CE EJB, the Principal name is extracted from the JAAS subject, and it is
searched for in the CE user cache. If the Principal name is not found, CE calls the
enterprise directory service to expand the caller's identity information.
7. The EJB processes the request. A FileNet P8 identity token is created and returned to
the PE Java API.
8. If the preceding steps are successful, the PE Java API makes a call to the PE server
and passes the identity token as a parameter. The PE server examines the identity
token, and the signature on it is validated.
9. This optional step is unrelated to the authentication process, but occurs in many cases.
PE retrieves the detailed user information (full name, domain name, email address,
group memberships, and so forth) by calling CE to retrieve the requested user and
group objects.

3-12 IBM FileNet BPM 5.0: Java API Programming © Copyright IBM Corp. 2011
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
V5.4
Student Notebook

Uempty
Create a Process Engine session
VWSession object
• The VWSession object establishes a session and logs on to a
Process Engine.
• Call the VWSession(…) constructor
– Parameters:
• User name and password to log on
• Name of the connection point
• VWSession object is used by
– Runtime API
– Administration and configuration API
• VWSession object allows
– Querying rosters and queues
– Retrieving lists of roster and queue names
– Administering the system

© Copyright IBM Corporation 2011

Figure 3-9. VWSession object F1561.0

Notes:

© Copyright IBM Corp. 2011 Unit 3. Log On to the Process Engine 3-13
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
Student Notebook

Create a Process Engine session

VWSession constructor options

VWSession() Parameters Functionality

String user
Establishes a new session based on a specified
String password connection point.
String connectionPointName

Creates a new session in an environment where

String url the Java™ Authentication and Authorization
Service (JAAS) context is already established.

String domain, String user

Establishes a session for a specified domain and
String password connection point.
String connectionPointName

No parameters Used with FileNet Web Services or Open Client.

© Copyright IBM Corporation 2011

Figure 3-10. VWSession constructor options F1561.0

Notes:
The table in this page lists the different VWSession constructors and describes their
functionality.
In the case of a VWSession constructor() with no parameters, a logon method is called,
and logon information and the name of the connection point are passed in to the logon
method.

3-14 IBM FileNet BPM 5.0: Java API Programming © Copyright IBM Corp. 2011
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
V5.4
Student Notebook

Uempty
Create a Process Engine session
Steps to log on to and log off from the Process Engine

• Log on to the Process Engine

myPESession
myPESession == new
new VWSession(…)
VWSession(…)

• Log off from the Process Engine

vwSession.logoff()
vwSession.logoff()

© Copyright IBM Corporation 2011

Figure 3-11. Steps to log on to and log off from the Process Engine F1561.0

Notes:

© Copyright IBM Corp. 2011 Unit 3. Log On to the Process Engine 3-15
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
Student Notebook

Create a Process Engine session

VWSession constructor

public
public VWSession(String
VWSession(String user,
user,
String
String password,String
password,String connectionPointName)
connectionPointName)

• Parameters
–user — Specify the user name to connect
–password — Specify the password associated with the user name
–connectionPointName — Specify the name of the connection point to
use for this session
• Returns
–A VWSession object
• Notes
–This method establishes a new session based on a specified
connection point.
–This method throws a VWException if the logon fails.
© Copyright IBM Corporation 2011

Figure 3-12. VWSession constructor F1561.0

Notes:

3-16 IBM FileNet BPM 5.0: Java API Programming © Copyright IBM Corp. 2011
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
V5.4
Student Notebook

Uempty
Create a Process Engine session
vwSession.logon(…)

public
public void
void logon(String
logon(String user,
user,
String
String password,String
password,String connectionPointName)
connectionPointName)
• Parameters
–user — Specify a user name that has permission to log on to the
Process Engine
–password — Specify the password associated with the user name
–connectionPointName — Specify the name of the connection point to
use for this session
• Notes
–This method logs on to an existing session.

© Copyright IBM Corporation 2011

Figure 3-13. vwSession.logon(...) F1561.0

Notes:

© Copyright IBM Corp. 2011 Unit 3. Log On to the Process Engine 3-17
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
Student Notebook

Create a Process Engine session

vwSession.logoff()

public
public void
void logoff()
logoff()

• Parameters
–None
• Notes
–This method ends the session with the Process Engine and frees all
resources.
–The system calls this method internally.
–Make an explicit call as soon as possible to conserve resources.
–This method throws a VWException if the method cannot end the
session with the Process Engine.

© Copyright IBM Corporation 2011

Figure 3-14. vwSession.logoff() F1561.0

Notes:
This method ends the session with the Process Engine and frees all resources.
Although the system calls this method internally, an explicit call makes finalization more
immediate and certain. Otherwise, finalization is uncertain even when the Java Virtual
Machine (JVM) shuts down.

3-18 IBM FileNet BPM 5.0: Java API Programming © Copyright IBM Corp. 2011
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
V5.4
Student Notebook

Uempty
Create a Process Engine session
Sample code to log on to and log off from PE
• Log on to the Process Engine
myPESession
myPESession == new
new VWSession(userName,
VWSession(userName,
password,
password, connectionPoint)
connectionPoint)

• Log off from the Process Engine

…
…
vwSession.logoff()
vwSession.logoff()

© Copyright IBM Corporation 2011

Figure 3-15. Sample code to log on to and log off from PE F1561.0

Notes:

© Copyright IBM Corp. 2011 Unit 3. Log On to the Process Engine 3-19
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
Student Notebook

Create a Process Engine session

Sample code to log on to the Process Engine (JSP)
• Get the logon information from the user on a JSP page.
String
String LogonName
LogonName == request.getParameter("username");
request.getParameter("username");
String
String Password
Password == request.getParameter
request.getParameter ("password");
("password");
String ConnectionPoint =request.getParameter
String ConnectionPoint =request.getParameter
("connectionPoint");
("connectionPoint");
• Create a Process Engine session.
myPESession
myPESession == new
new VWSession()
VWSession()
• Set BootstrapCEURI and call the logon.
myPESession.setBootstrapCEURI
myPESession.setBootstrapCEURI
("cemp:iiop://<serverName>:2809/FileNet/Engine");
("cemp:iiop://<serverName>:2809/FileNet/Engine");
myPESession.logon(userName,password,
myPESession.logon(userName,password,
connectionPoint));
connectionPoint));
...
...
myPESession.logoff();
myPESession.logoff();
© Copyright IBM Corporation 2011

Figure 3-16. Sample code to log on to the Process Engine (JSP) F1561.0

Notes:

3-20 IBM FileNet BPM 5.0: Java API Programming © Copyright IBM Corp. 2011
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
V5.4
Student Notebook

Uempty
Create a Process Engine session
Demonstrations
• Create a Process Engine session.
–Explore the code sample.
–Run the solution code.
–Observe the results.

© Copyright IBM Corporation 2011

Figure 3-17. Demonstrations F1561.0

Notes:
Demonstration notes
1. Start Eclipse and open the BPMJavaAPISolution project.
2. Review the code for the peLogonEDU (…) method in the PESessionEDU.java file.
3. Run the code and verify the results as instructed in the “Log On to the Process Engine”
unit in the Student Exercises.
4. Repeat steps 2 and 3 for the peLogoffEDU (…) method that end the session and
releases the resources.

© Copyright IBM Corp. 2011 Unit 3. Log On to the Process Engine 3-21
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
Student Notebook

Create a Process Engine session

Activities
In your Student Exercises
• Unit: Log On to the Process Engine
• Lesson: Create a Process Engine session
• Activities:
– Create a Process Engine session

© Copyright IBM Corporation 2011

Figure 3-18. Activities F1561.0

Notes:
Use your Student Exercises to perform the activities listed.

3-22 IBM FileNet BPM 5.0: Java API Programming © Copyright IBM Corp. 2011
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
V5.4
Student Notebook

Uempty Lesson 3.2. Handle exceptions

© Copyright IBM Corp. 2011 Unit 3. Log On to the Process Engine 3-23
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
Student Notebook

Lesson:
Handle exceptions
• Why is this lesson important to you?
– You are writing code to log on to the Process Engine and to process
the workflows. You want to catch any exceptions thrown and display
the messages.

© Copyright IBM Corporation 2011

Figure 3-19. Lesson: Handle exceptions F1561.0

Notes:

3-24 IBM FileNet BPM 5.0: Java API Programming © Copyright IBM Corp. 2011
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
V5.4
Student Notebook

Uempty
Handle exceptions
Activities that you need to complete

• Handle a VWException.

© Copyright IBM Corporation 2011

Figure 3-20. Activities that you need to complete F1561.0

Notes:
These are the activities that you are going to perform in this lesson.

© Copyright IBM Corp. 2011 Unit 3. Log On to the Process Engine 3-25
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
Student Notebook

Handle exceptions
VWException object
• This object is the base class for all workflow exceptions.
• String properties of the VWException object
–Key — Key to use in looking up a resource in the VWExceptions file
• Tells which interface produced the exception, and so forth
–Message — Contains the associated string for the key from the
exceptions resource file
• Customized messages can be obtained from the exceptions
resource file.
• English version of resource string, which the application uses to
generate the VWExceptions file

© Copyright IBM Corporation 2011

Figure 3-21. VWException object F1561.0

Notes:
Help path
• IBM FileNet P8 Version 5.0 Information Center > Developing IBM FileNet P8
applications > Process Engine Development > Process Engine error messages > Client
Error messages
If you pass an invalid connection point name, the following are the examples of an
Exception message:
VWException Key: pe.ceutils.ConnectionPoints.ConnectionPointIsNotFound
VWException Cause Class Name: null
VWException CauseDescription: null
VWException Message: ConnectionPoint RegionFive1 is not found for
http://ccv01135:9080/wsi/FNCEWS40MTOM/
If you pass an invalid user name or password, the following are the examples of an
Exception message:

3-26 IBM FileNet BPM 5.0: Java API Programming © Copyright IBM Corp. 2011
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
V5.4
Student Notebook

Uempty VWException Cause Class Name: com.filenet.api.exception.EngineRuntimeException

VWException CauseDescription: The user is not authenticated.
VWException Key: null
VWException Message: com.filenet.api.exception.EngineRuntimeException:
FNRCE0040E: E_NOT_AUTHENTICATED: The user is not authenticated.

© Copyright IBM Corp. 2011 Unit 3. Log On to the Process Engine 3-27
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
Student Notebook

Handle exceptions
Steps to handle a VWException

1. Start a try-catch block.

try
try {{

2. Call a method that can throw a VWException.

...
...

3. Catch the exception, and identify and handle the error.

}}
catch
catch (VWException
(VWException vwe)
vwe) {{
...
... vwe.getKey()
vwe.getKey() ...
...
...
... vwe.getCauseClassName()
vwe.getCauseClassName() ...
...
...
... vwe.getCauseDescription()...
vwe.getCauseDescription()...
...
... vwe.getMessage()...
vwe.getMessage()...
}}
© Copyright IBM Corporation 2011

Figure 3-22. Steps to handle a VWException F1561.0

Notes:

3-28 IBM FileNet BPM 5.0: Java API Programming © Copyright IBM Corp. 2011
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
V5.4
Student Notebook

Uempty
Handle exceptions
vwException.getKey()

public
public String
String getKey()
getKey()

• Parameters
–None
• Returns
–The key to an exception

© Copyright IBM Corporation 2011

Figure 3-23. vwException.getKey() F1561.0

Notes:

© Copyright IBM Corp. 2011 Unit 3. Log On to the Process Engine 3-29
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
Student Notebook

Handle exceptions
vwException.getCauseClassName()

public
public String
String getCauseClassName()
getCauseClassName()

• Parameters
–None
• Returns
–The class name for the cause of this VWException
–Null if the cause is nonexistent or unknown

© Copyright IBM Corporation 2011

Figure 3-24. vwException.getCauseClassName() F1561.0

Notes:

3-30 IBM FileNet BPM 5.0: Java API Programming © Copyright IBM Corp. 2011
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
V5.4
Student Notebook

Uempty
Handle exceptions
vwException.getCauseDescription()

public
public String
String getCauseDescription()
getCauseDescription()

• Parameters
–None
• Returns
–A string representing the description for the cause of this
VWException
–Null if the cause is nonexistent or unknown

© Copyright IBM Corporation 2011

Figure 3-25. vwException.getCauseDescription() F1561.0

Notes:

© Copyright IBM Corp. 2011 Unit 3. Log On to the Process Engine 3-31
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
Student Notebook

Handle exceptions
vwException.getMessage()

public
public String
String getMessage()
getMessage()

• Parameters
–None
• Returns
–The associated string of the exception file, if the string is available
–The default value for the exception key, if the string is not available

© Copyright IBM Corporation 2011

Figure 3-26. vwException.getMessage() F1561.0

Notes:

3-32 IBM FileNet BPM 5.0: Java API Programming © Copyright IBM Corp. 2011
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
V5.4
Student Notebook

Uempty
Handle exceptions
Sample code to handle an exception
try
try {{
myPESession
myPESession == new
new VWSession
VWSession
(user,password,connectionPointName);
(user,password,connectionPointName);
}}
catch
catch (VWException
(VWException vwe)
vwe) {{
System.out.println("\nVWException
System.out.println("\nVWException Key:Key: "" ++
vwe.getKey()
vwe.getKey() ++ "\n");
"\n");
System.out.println("VWException Cause Class
System.out.println("VWException Cause Class
Name:
Name: "" ++ vwe.getCauseClassName()
vwe.getCauseClassName() ++ "\n");
"\n");
System.out.println("VWException
System.out.println("VWException
CauseDescription:
CauseDescription: ““ ++
vwe.getCauseDescription()+
vwe.getCauseDescription()+ "\n“);
"\n“);
System.out.println("VWException
System.out.println("VWException Message:
Message: "" ++
vwe.getMessage());
vwe.getMessage());
}}

© Copyright IBM Corporation 2011

Figure 3-27. Sample code to handle an exception F1561.0

Notes:

© Copyright IBM Corp. 2011 Unit 3. Log On to the Process Engine 3-33
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
Student Notebook

Handle exceptions
Demonstrations
• Handle a VWException.
–Explore the code sample.
–Run the solution code.
–Observe the results.

© Copyright IBM Corporation 2011

Figure 3-28. Demonstrations F1561.0

Notes:
Demonstration notes
1. Start Eclipse and open the BPMJavaAPISolution project.
2. Review the code for the catch(VWException vwe) block in the peLogonEDU (…)
method in the PESessionEDU.java file.
3. Enter an invalid logon name, password, or connection point to view the exception
messages that are displayed.
4. Run the code and verify the results as instructed in the “Log On to the Process Engine”
unit in the Student Exercises.

3-34 IBM FileNet BPM 5.0: Java API Programming © Copyright IBM Corp. 2011
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
V5.4
Student Notebook

Uempty
Handle exceptions
Activities
In your Student Exercises
• Unit: Log On to the Process Engine
• Lesson: Handle exceptions
• Activities:
–Handle a VWException.

© Copyright IBM Corporation 2011

Figure 3-29. Activities F1561.0

Notes:
Use your Student Exercises to perform the activities listed.

© Copyright IBM Corp. 2011 Unit 3. Log On to the Process Engine 3-35
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
Student Notebook

3-36 IBM FileNet BPM 5.0: Java API Programming © Copyright IBM Corp. 2011
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
V5.4
Student Notebook

Uempty Lesson 3.3. Retrieve user and group information

© Copyright IBM Corp. 2011 Unit 3. Log On to the Process Engine 3-37
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
Student Notebook

Lesson:
Retrieve user and group information
• Why is this lesson important to you?
– The accounting department wants to be able to send email
updates based on Process Engine activity. As the programmer,
you need to retrieve the email addresses of users from the
Process Engine.

© Copyright IBM Corporation 2011

Figure 3-30. Lesson: Retrieve user and group information F1561.0

Notes:

3-38 IBM FileNet BPM 5.0: Java API Programming © Copyright IBM Corp. 2011
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
V5.4
Student Notebook

Uempty
Retrieve user and group information
Activities that you need to complete

• Retrieve user and group information.

© Copyright IBM Corporation 2011

Figure 3-31. Activities that you need to complete F1561.0

Notes:
These are the activities that you are going to perform in this lesson.

© Copyright IBM Corp. 2011 Unit 3. Log On to the Process Engine 3-39
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
Student Notebook

Retrieve user and group information

Steps to get current user information

1. Get the VWUserInfo object for the current user.

vwSession.fetchCurrentUserInfo()
vwSession.fetchCurrentUserInfo()

2. Get the name of the current user.

vwUserInfo.getName()
vwUserInfo.getName()

3. Get the email address of the current user.

vwUserInfo.getEMailAddress()
vwUserInfo.getEMailAddress()

4. Get the name of the assigned proxy user for the current
user.
vwUserInfo.getProxyUserName()
vwUserInfo.getProxyUserName()

© Copyright IBM Corporation 2011

Figure 3-32. Steps to get current user information F1561.0

Notes:

3-40 IBM FileNet BPM 5.0: Java API Programming © Copyright IBM Corp. 2011
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
V5.4
Student Notebook

Uempty
Retrieve user and group information
vwSession.fetchCurrentUserInfo()

public
public VWUserInfo
VWUserInfo fetchCurrentUserInfo()
fetchCurrentUserInfo()

• Parameters
–None
• Returns
–A VWUserInfo object containing information about the current user
who is logged on to this session

© Copyright IBM Corporation 2011

Figure 3-33. vwSession.fetchCurrentUserInfo() F1561.0

Notes:

© Copyright IBM Corp. 2011 Unit 3. Log On to the Process Engine 3-41
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
Student Notebook

Retrieve user and group information

vwUserInfo.getName()

public
public String
String getName()
getName()

• Parameters
–None
• Returns
–The name of the current user

© Copyright IBM Corporation 2011

Figure 3-34. vwUserInfo.getName() F1561.0

Notes:

3-42 IBM FileNet BPM 5.0: Java API Programming © Copyright IBM Corp. 2011
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
V5.4
Student Notebook

Uempty
Retrieve user and group information
vwUserInfo.getEMailAddress()

public
public String
String getEMailAddress()
getEMailAddress()

• Parameters
–None
• Returns
–The email address of the current user
• Notes
–You need to define the email address and other information of the
current user in User Preferences of the Workplace (Tasks link).
–Process Engine API accesses these preference settings.

© Copyright IBM Corporation 2011

Figure 3-35. vwUserInfo.getEMailAddress() F1561.0

Notes:

© Copyright IBM Corp. 2011 Unit 3. Log On to the Process Engine 3-43
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
Student Notebook

Retrieve user and group information

vwUserInfo.getProxyUserName()

public
public String
String getMessage()
getMessage()

• Parameters
–None
• Returns
–The proxy user name for the current user
• Notes
–You need to define the proxy user name and other information of the
current user in User Preferences of the Workplace (Tasks Settings).
–Process Engine API accesses these preference settings.
–A proxy user receives work items on behalf of the current user.

© Copyright IBM Corporation 2011

Figure 3-36. vwUserInfo.getProxyUserName() F1561.0

Notes:
A proxy user receives work items on behalf of the current user.

3-44 IBM FileNet BPM 5.0: Java API Programming © Copyright IBM Corp. 2011
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
V5.4
Student Notebook

Uempty
Retrieve user and group information
Sample code to get current user information
VWUserInfo
VWUserInfo userInfo;
userInfo;
userInfo
userInfo ==
myPESession.fetchCurrentUserInfo();
myPESession.fetchCurrentUserInfo();
System.out.println("Current
System.out.println("Current User:
User: "" ++
userInfo.getName());
userInfo.getName());
System.out.println("email:
System.out.println("email: "" ++
userInfo.getEMailAddress());
userInfo.getEMailAddress());
System.out.println("Proxy:
System.out.println("Proxy: "" ++
userInfo.getProxyUserName());
userInfo.getProxyUserName());

© Copyright IBM Corporation 2011

Figure 3-37. Sample code to get current user information F1561.0

Notes:
In the code, assume that the VWSession type variable called myPESession has already
been assigned a valid value (after successfully logging on to the Process Engine.)

© Copyright IBM Corp. 2011 Unit 3. Log On to the Process Engine 3-45
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
Student Notebook

Retrieve user and group information

Steps to get the LDAP users and groups

1. Retrieve the LDAP users.

vwSession.findUsers(…)
vwSession.findUsers(…)

2. Retrieve the Process Engine ID for the user name.

vwSession.convertUserNameToId(…)
vwSession.convertUserNameToId(…)

3. Retrieve the LDAP groups.

vwSession.findGroups(…)
vwSession.findGroups(…)

4. Retrieve the Process Engine ID for the group name.

vwSession.convertUserNameToId(…)
vwSession.convertUserNameToId(…)

© Copyright IBM Corporation 2011

Figure 3-38. Steps to get the LDAP users and groups F1561.0

Notes:

3-46 IBM FileNet BPM 5.0: Java API Programming © Copyright IBM Corp. 2011
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
V5.4
Student Notebook

Uempty
Retrieve user and group information
vwSession.findUsers(…)

public
public VWSecurityList
VWSecurityList findUsers
findUsers
(String
(String searchPattern,
searchPattern, int
int searchType,
searchType,
int
int sortType,int
sortType,int maxBufferSize)
maxBufferSize)
• Parameters
–searchPattern — Specify a string for comparison. The string is used
to determine if a name matches.
–searchType — Specify the way the comparison search pattern String
is used.
–sortType — Specify the type of sorting the security database server
performs on the returned set of records.
–maxBufferSize — Specify the maximum number of elements to
return in a fetch.
• Returns
–A VWSecurityList object that holds a collection of user names for the
Process Engine system
© Copyright IBM Corporation 2011

Figure 3-39. vwSession.findUsers(...) F1561.0

Notes:
Parameters:
searchPattern - Comparison is performed according to the method specified by the
searchType parameter. Null is allowable for a searchType of SEARCH_TYPE_NONE.
searchType - Allowed values are as follows:
0: SEARCH_TYPE_NONE
Matches all names and ignores the searchPattern string. Can cause
performance degradation for large databases.
1: SEARCH_TYPE_CUSTOM
Matches when the search pattern is an exact match.
2: SEARCH_TYPE_PREFIX_MATCH
Matches when the search pattern has an exact match at the beginning of the
name.

© Copyright IBM Corp. 2011 Unit 3. Log On to the Process Engine 3-47
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
Student Notebook

3: SEARCH_TYPE_SUFFIX_MATCH
Matches when the search pattern has an exact match at the end of the name.
4: SEARCH_TYPE_CONTAINS
Matches when the search pattern has an exact match anywhere within the
name.
sortType - Specifies the type of sorting the security database server performs on the
returned set of records, as follows:
0: SORT_TYPE_NONE — No sort
1: SORT_TYPE_ASCENDING — Ascending sort
2: SORT_TYPE_DESCENDING — Descending sort
Note: If sorting fails on the security database server, an error is thrown and no results
are returned.
maxBufferSize - An integer value specifying the maximum number of elements to return in
a fetch. Specify a value with greater than 0 (zero), or use 0 (zero) or a negative value to
specify the default buffer size, which is 200.
Returns - A collection of user names for the Process Engine system that matches the input
search pattern searchPattern, using the comparison method specified by the searchType,
sorted according to sortType.

3-48 IBM FileNet BPM 5.0: Java API Programming © Copyright IBM Corp. 2011
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
V5.4
Student Notebook

Uempty
Retrieve user and group information
vwSession.convertUserNameToId(…)

public
public int
int convertUserNameToId
convertUserNameToId
(String
(String aUserName)
aUserName)

• Parameters
–aUserName — Specify the user name or group name
• Returns
–The internal Process Engine ID number for that user or group

© Copyright IBM Corporation 2011

Figure 3-40. vwSession.convertUserNameToId(...) F1561.0

Notes:
This method invokes a call to the Process Engine if there has been no previous server call
to get user names. If the system does not find the user name, the method performs an
additional RPC internally to retrieve an updated list of user names.

© Copyright IBM Corp. 2011 Unit 3. Log On to the Process Engine 3-49
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
Student Notebook

Retrieve user and group information

vwSession.findGroups(…)

public
public VWSecurityList
VWSecurityList findGroups
findGroups
(String
(String searchPattern,int
searchPattern,int searchType,
searchType,
int sortType, int maxBufferSize)
int sortType, int maxBufferSize)
• Parameters
–searchPattern — Specify a string for comparison. The string is used
to determine if a name matches.
–searchType — Specify the way the comparison search pattern String
is used.
–sortType — Specify the type of sorting the security database server
performs on the returned set of records.
–maxBufferSize — Specify the maximum number of elements to
return in a fetch.
• Returns
–A VWSecurityList object that holds a collection of group names for
the Process Engine system
© Copyright IBM Corporation 2011

Figure 3-41. vwSession.findGroups(...) F1561.0

Notes:

3-50 IBM FileNet BPM 5.0: Java API Programming © Copyright IBM Corp. 2011
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
V5.4
Student Notebook

Uempty
Retrieve user and group information
Sample code to get the current Process Engine user

VWUserInfo
VWUserInfo userInfo
userInfo ==
myPESession.fetchCurrentUserInfo();
myPESession.fetchCurrentUserInfo();
System.out.println("Current
System.out.println("Current User:\t"
User:\t" ++
userInfo.getName());
userInfo.getName());
System.out.println("email:\t"
System.out.println("email:\t" ++
userInfo.getEMailAddress());
userInfo.getEMailAddress());
System.out.println("Proxy:\t"
System.out.println("Proxy:\t" ++
userInfo.getProxyUserName());
userInfo.getProxyUserName());

• In the code, assume that the VWSession type variable, called

myPESession, has already been assigned a valid value after
successfully logging on to the Process Engine.

© Copyright IBM Corporation 2011

Figure 3-42. Sample code to get the current Process Engine user F1561.0

Notes:
In the code, assume that the VWSession type variable called myPESession has already
been assigned a valid value (after successfully logging on to the Process Engine).

© Copyright IBM Corp. 2011 Unit 3. Log On to the Process Engine 3-51
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
Student Notebook

Retrieve user and group information

Sample code to get the Process Engine users
• Retrieve and display users and their Process Engine internal
ID numbers
System.out.println("User
System.out.println("User NameName \t(ID)");
\t(ID)");
VWSecurityList
VWSecurityList users
users == myPESession.findUsers
myPESession.findUsers
("m",VWSession.SEARCH_TYPE_PREFIX_MATCH,
("m",VWSession.SEARCH_TYPE_PREFIX_MATCH,
VWSession.SORT_TYPE_NONE,
VWSession.SORT_TYPE_NONE, -1);
-1);
String
String userName;
userName;
int userID;
int userID;
while
while (users.hasNext())
(users.hasNext()) {{
userName
userName == (String)
(String) users.next();
users.next();
userID
userID == myPESession.convertUserNameToId
myPESession.convertUserNameToId
(userName);
(userName);
System.out.println(userName
System.out.println(userName ++ "\t("
"\t(" ++
userID
userID ++ ")");
")");
}}
© Copyright IBM Corporation 2011

Figure 3-43. Sample code to get the Process Engine users F1561.0

Notes:
In the code, assume that the VWSession type variable called myPESession has already
been assigned a valid value (after successfully logging on to the Process Engine.)

3-52 IBM FileNet BPM 5.0: Java API Programming © Copyright IBM Corp. 2011
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
V5.4
Student Notebook

Uempty
Retrieve user and group information
Sample code to get the Process Engine groups
• Retrieve and display groups and their Process Engine internal
ID numbers.
VWSecurityList
VWSecurityList groups
groups == myPESession.findGroups
myPESession.findGroups
("m",VWSession.SEARCH_TYPE_PREFIX_MATCH,
("m",VWSession.SEARCH_TYPE_PREFIX_MATCH,
VWSession.SORT_TYPE_NONE,100);
VWSession.SORT_TYPE_NONE,100);
String
String groupName;
groupName;
int
int groupID;
groupID;
while
while (groups.hasNext())
(groups.hasNext())
groupName
groupName == (String)
(String) groups.next();
groups.next();
groupID
groupID == myPESession.convertUserNameToId
myPESession.convertUserNameToId
(groupName)
(groupName)
System.out.println(groupName
System.out.println(groupName ++ "\t("
"\t(" ++ groupID
groupID ++
")");
")");
}}
© Copyright IBM Corporation 2011

Figure 3-44. Sample code to get the Process Engine groups F1561.0

Notes:
In the code, assume that the VWSession type variable called myPESession has already
been assigned a valid value (after successfully logging on to the Process Engine.)

© Copyright IBM Corp. 2011 Unit 3. Log On to the Process Engine 3-53
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
Student Notebook

Retrieve user and group information

Demonstrations
• Retrieve user and group information.
–Explore the code sample.
–Run the solution code.
–Observe the results.

© Copyright IBM Corporation 2011

Figure 3-45. Demonstrations F1561.0

Notes:
Demonstration notes
1. Start Eclipse and open the BPMJavaAPISolution project.
2. Review the code for the getUsersAndGroupsEDU (…) method in the
PESessionEDU.java file.
3. Run the code and verify the results as instructed in the “Log On to the Process Engine”
unit in the Student Exercises.

3-54 IBM FileNet BPM 5.0: Java API Programming © Copyright IBM Corp. 2011
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
V5.4
Student Notebook

Uempty
Retrieve user and group information
Activities
In your Student Exercises
• Unit: Log On to the Process Engine
• Lesson: Retrieve user and group information
• Activities:
– Retrieve user and group information.

© Copyright IBM Corporation 2011

Figure 3-46. Activities F1561.0

Notes:
Use your Student Exercises to perform the activities listed.

© Copyright IBM Corp. 2011 Unit 3. Log On to the Process Engine 3-55
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
Student Notebook

3-56 IBM FileNet BPM 5.0: Java API Programming © Copyright IBM Corp. 2011
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
V5.4
Student Notebook

Uempty Unit 4. Create Work

What this unit is about

This unit describes how to write code using Process Engine Java API
to do the following:
Retrieve workflows and launch a workflow
Retrieve parameter values for a step element
Set parameter values for a step element
This unit also describes how to set up a workflow subscription and an
entry template to automatically launch a workflow.

What you should be able to do

After completing this unit, you should be able to:
• Launch a workflow.
• Retrieve parameter values for a step element.
• Set parameter values for a step element.
• Automatically launch a workflow using a subscription.
• Build a document entry template with a workflow.

How you will check your progress

• Successfully complete the activities in the Student Exercises book.

References
www.ibm.com/support/documentation/us/en (Support & downloads
page)
Note: IBM FileNet products belong to the Information Management
product set.

© Copyright IBM Corp. 2011 Unit 4. Create Work 4-1

Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
Student Notebook

Create Work
Unit lessons
This unit contains the following lessons:
• Retrieve and launch a workflow
• Retrieve parameter values for a step element
• Set parameter values for a step element
• Automatically launch a workflow

© Copyright IBM Corporation 2011

Figure 4-1. Unit lessons F1561.0

Notes:
Lessons in this unit
This unit has four lessons. After the first lesson, each lesson relies on information and skills
taught in the prior lessons. For best results, do these lessons in the sequence presented.
Retrieve and launch a workflow – In this lesson, you write code to select a workflow,
launch a workflow, and dispatch work objects.
Retrieve parameter values for a step element – In this lesson, you write code to retrieve
parameter values for a step element.
Set parameter values for a step element – In this lesson, you write code to set parameter
values for a step element with customer data.
Automatically launch a workflow – In this lesson, you set up a workflow subscription to
automatically launch a workflow. You also set up an entry template to automatically launch
a workflow.

4-2 IBM FileNet BPM 5.0: Java API Programming © Copyright IBM Corp. 2011
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
V5.4
Student Notebook

Uempty Lesson 4.1. Retrieve and launch a workflow

© Copyright IBM Corp. 2011 Unit 4. Create Work 4-3

Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
Student Notebook

Lesson:
Retrieve and launch a workflow
• Why is this lesson important to you?
–Your company uses workflows for many tasks, such as processing a
customer order. As their programmer, you are going to write code to
create work which includes launching a workflow and dispatching a
work object. You are going to also retrieve workflows to choose from
for launching.

© Copyright IBM Corporation 2011

Figure 4-2. Lesson: Retrieve and launch a workflow F1561.0

Notes:

4-4 IBM FileNet BPM 5.0: Java API Programming © Copyright IBM Corp. 2011
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
V5.4
Student Notebook

Uempty
Retrieve and launch a workflow
Activities that you need to complete

• Launch a workflow.

© Copyright IBM Corporation 2011

Figure 4-3. Activities that you need to complete F1561.0

Notes:
These are the activities that you are going to perform in this lesson.

© Copyright IBM Corp. 2011 Unit 4. Create Work 4-5

Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
Student Notebook

Retrieve and launch a workflow

Steps to retrieve and launch a workflow

1. Obtain the VWSession.

vwSession
vwSession mySession
mySession == new
new VWSession(…)
VWSession(…)

2. Retrieve the workflow definition (work class) names from

the VWSession object.
vwSession.fetchWorkClassNames(…)
vwSession.fetchWorkClassNames(…)

3. Create the workflow for the selected work class.

vwSession.createWorkflow(…)
vwSession.createWorkflow(…)

4. Retrieve and set workflow VW parameters for the launch.

step.
This
This will
will be
be covered
covered in
in the
the next
next lessons.
lessons.

5. Dispatch the launch step.

vwStepElement.doDispatch()
vwStepElement.doDispatch()
© Copyright IBM Corporation 2011

Figure 4-4. Steps to retrieve and launch a workflow F1561.0

Notes:

4-6 IBM FileNet BPM 5.0: Java API Programming © Copyright IBM Corp. 2011
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
V5.4
Student Notebook

Uempty
Retrieve and launch a workflow
vwSession.fetchWorkClassNames(…)

public
public String[]
String[] fetchWorkClassNames
fetchWorkClassNames
(boolean
(boolean ignoreSecurity)
ignoreSecurity)

• Parameters
–ignoreSecurity – Specify a Boolean value:
• True to return the names of all work classes, including those that
this user is not authorized to access
• False to return only the names of work classes that this user is
authorized to access
• Returns
–A list of work class names within the isolated region
• Notes
–This method throws VWException for various causes,
including communications, server, and connection problems.
© Copyright IBM Corporation 2011

Figure 4-5. vwSession.fetchWorkClassNames(...) F1561.0

Notes:

© Copyright IBM Corp. 2011 Unit 4. Create Work 4-7

Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
Student Notebook

Retrieve and launch a workflow

vwSession.createWorkflow(…)

public
public VWStepElement
VWStepElement createWorkflow
createWorkflow
(String
(String workflowIdentifier)
workflowIdentifier)

• Parameters
–workflowIdentifier – Specify the Workflow definition (work class)
name in a String.
• Returns
–A VWStepElement object that represents the launch step for the
workflow
• Notes
–This method launches the specified workflow defined by a transferred
workflow definition.

© Copyright IBM Corporation 2011

Figure 4-6. vwSession.createWorkflow(...) F1561.0

Notes:
This method throws VWException if these events occur:
• The workflow definition specified by the workflowIdentifier parameter does not exist on
the Process Engine.
• There are network problems connecting to the Process Engine.

4-8 IBM FileNet BPM 5.0: Java API Programming © Copyright IBM Corp. 2011
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
V5.4
Student Notebook

Uempty
Retrieve and launch a workflow
vwStepElement.doDispatch()

public
public void
void doDispatch()
doDispatch()

• Notes
–This method saves changes made to the work object
associated with this step element.
–This method also unlocks the work object and advances the
work object in the workflow

© Copyright IBM Corporation 2011

Figure 4-7. vwStepElement.doDispatch() F1561.0

Notes:

© Copyright IBM Corp. 2011 Unit 4. Create Work 4-9

Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
Student Notebook

Retrieve and launch a workflow

Sample code to retrieve and launch a workflow
• Retrieve a workflow.
String[]
String[] workClassNames
workClassNames ==
myPESession.fetchWorkClassNames(true);
myPESession.fetchWorkClassNames(true);
for
for (int
(int i=0;i<workClassNames.length;i++)
i=0;i<workClassNames.length;i++)
System.out.println(workClassNames[i]
System.out.println(workClassNames[i] );
);

• Launch a workflow.
VWStepElement
VWStepElement stepElement
stepElement ==
vwSession.createWorkflow(workclass);
vwSession.createWorkflow(workclass);
stepElement.doDispatch();
stepElement.doDispatch();

© Copyright IBM Corporation 2011

Figure 4-8. Sample code to retrieve and launch a workflow F1561.0

Notes:
For the method vwSession.createWorkflow(…), you can send the workflow name as the
parameter or send the workflow that you retrieved.
To choose a specific version of the workflow to be launched, use the VWVersion property
value (instead of the name of the workflow) of the specific workflow version.

4-10 IBM FileNet BPM 5.0: Java API Programming © Copyright IBM Corp. 2011
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
V5.4
Student Notebook

Uempty
Retrieve and launch a workflow
Demonstrations
• Launch a workflow.
–Explore the code sample.
–Run the solution code.
–Observe the results.

© Copyright IBM Corporation 2011

Figure 4-9. Demonstrations F1561.0

Notes:
Demonstration notes
1. Start Eclipse and open the BPMJavaAPISolution project.
2. Review the code for retrieving the workflows in the launchEDU(…) method in the
CreateWorkEDU.java file.
3. Run the code and verify the results as instructed in the “Create Work” unit in the
Student Exercises.
4. Repeat steps 2 and 3 for the code for launching a workflow using a workflow name as
well as a specific version of the workflow (using VWVersion property value) using the
same method and Java file.

© Copyright IBM Corp. 2011 Unit 4. Create Work 4-11

Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
Student Notebook

Retrieve and launch a workflow

Activities
In your Student Exercises
• Unit: Create work
• Lesson: Retrieve and launch a workflow
• Activities:
–Launch a workflow.

© Copyright IBM Corporation 2011

Figure 4-10. Activities F1561.0

Notes:
Use your Student Exercises to perform the activities listed.

4-12 IBM FileNet BPM 5.0: Java API Programming © Copyright IBM Corp. 2011
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
V5.4
Student Notebook

Uempty Lesson 4.2. Retrieve parameter values for a step element

© Copyright IBM Corp. 2011 Unit 4. Create Work 4-13

Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
Student Notebook

Lesson:
Retrieve parameter values for a step element
• Why is this lesson important to you?
– Your company handles customer orders that contain workflows with
customer data for processing. As the programmer, you are going to
write code to get parameter values for a step element that are used
to set the values with customer data.

© Copyright IBM Corporation 2011

Figure 4-11. Lesson: Retrieve parameter values for a step element F1561.0

Notes:

4-14 IBM FileNet BPM 5.0: Java API Programming © Copyright IBM Corp. 2011
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
V5.4
Student Notebook

Uempty
Retrieve parameter values for a step element
Activities that you need to complete

• Retrieve parameters values for a step.

© Copyright IBM Corporation 2011

Figure 4-12. Activities that you need to complete F1561.0

Notes:
These are the activities that you are going to perform in this lesson.

© Copyright IBM Corp. 2011 Unit 4. Create Work 4-15

Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
Student Notebook

Retrieve parameter values for a step element

Steps to retrieve parameters values
1. Retrieve the step element name and description.
vwStepElement.getStepName()
vwStepElement.getStepName()
vwStepElement.getStepDescription()
vwStepElement.getStepDescription()
2. Retrieve the user- and system-defined parameters.
vwStepElement.getParameters(…)
vwStepElement.getParameters (…)
3. Get the name, data type, read and write mode, and value for
each parameter.
vwParameter.getName()
vwParameter.getName()
VWFieldType.getLocalizedString(…)
VWFieldType.getLocalizedString(…)
VWModeType.getLocalizedString(…)
VWModeType.getLocalizedString(…)
vwParameter.getStringValue()
vwParameter.getStringValue()
4. Retrieve the step element responses.
vwStepElement.getStepResponses()
vwStepElement.getStepResponses()
© Copyright IBM Corporation 2011

Figure 4-13. Steps to retrieve parameters values F1561.0

Notes:

4-16 IBM FileNet BPM 5.0: Java API Programming © Copyright IBM Corp. 2011
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
V5.4
Student Notebook

Uempty
Retrieve parameter values for a step element
vwStepElement.getParameters(...)

public
public VWParameter[]
VWParameter[] getParameters
getParameters
(int
(int fieldTypeFlag,int fieldCreatorFlag)
fieldTypeFlag,int fieldCreatorFlag)

• Parameters
–fieldTypeFlag – Specify the parameter type or types.
–fieldCreatorFlag – Specify the field creator type (user, system, or
both).
• Returns
–An array of VWParameter objects: the system-defined, user-
defined, or both parameters in this step as specified in the
fieldCreatorFlag variable
–Null if no parameters exist or if the system cannot find parameters

© Copyright IBM Corporation 2011

Figure 4-14. vwStepElement.getParameters(...) F1561.0

Notes:
For the fieldTypeFlag parameter of this method, the following integer values (given in
parentheses) are valid.
Integer (FIELD_TYPE_INT)
String (FIELD_TYPE_STRING)
Boolean (FIELD_TYPE_BOOLEAN)
Float (FIELD_TYPE_FLOAT)
Time (FIELD_TYPE_TIME)
XML (FIELD_TYPE_XML)
Attachment (FIELD_TYPE_ATTACHMENT)
Participant (FIELD_TYPE_PARTICIPANT)
All types (ALL_FIELD_TYPES)
You can combine the flag types.

© Copyright IBM Corp. 2011 Unit 4. Create Work 4-17

Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
Student Notebook

For the fieldCreatorFlag parameter of this method, the following integer values (given in
parentheses) are valid.
User (FIELD_USER_DEFINED)
System (FIELD_SYSTEM_DEFINED)
User and System (FIELD_USER_AND_SYSTEM_DEFINED)

4-18 IBM FileNet BPM 5.0: Java API Programming © Copyright IBM Corp. 2011
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
V5.4
Student Notebook

Uempty
Retrieve parameter values for a step element
vwStepElement.getStepName()

public
public String
String getStepName()
getStepName()

• Parameters
–None
• Returns
–A String containing the step name
–Null if the field does not exist
• Notes
–This method overrides getStepName in the VWFieldsObject class.

© Copyright IBM Corporation 2011

Figure 4-15. vwStepElement.getStepName() F1561.0

Notes:
Additional methods on this object
The VWStepElement object also has the following method that is used in the activity for
this lesson:
• public String getStepDescription()
This method returns the description of the current step in a String.

© Copyright IBM Corp. 2011 Unit 4. Create Work 4-19

Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
Student Notebook

Retrieve parameter values for a step element

vwParameter. getFieldType()

public
public int
int getFieldType()
getFieldType()

• Parameters
–None
• Returns
–An integer value associated with the field type of the parameter
• Notes
–This method gets the field type for the parameter.

© Copyright IBM Corporation 2011

Figure 4-16. vwParameter. getFieldType() F1561.0

Notes:
Below are the list of VWFieldType Name with the Int Value in parenthesis and the
description (represents the workflow field type)
ALL_FIELD_TYPES( Values combined) - int, String, boolean, float, time, attachment
BASIC_FIELD_TYPES int, string, boolean, float, and time
FIELD_TYPE_ATTACHMENT(32) – Attachment (an attached document)
FIELD_TYPE_BOOLEAN(4)- java.lang.Boolean
FIELD_TYPE_FLOAT (8) - java.lang.Double
FIELD_TYPE_INT (1) - java.lang.Integer
FIELD_TYPE_PARTICIPANT( 64) - participant
FIELD_TYPE_STRING (2) - java.lang.String
FIELD_TYPE_TIME(16) - java.util.Date
FIELD_TYPE_XML(128) - XML

4-20 IBM FileNet BPM 5.0: Java API Programming © Copyright IBM Corp. 2011
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
V5.4
Student Notebook

Uempty
Retrieve parameter values for a step element
vwParameter.getMode()

public
public int
int getMode()
getMode()
• Parameters
–None
• Returns
–An integer value that indicates the mode of the step parameter
• Notes
–Valid modes returned are the following:
• MODE_TYPE_IN (1) if the mode of the VWParameter is read-
only
• MODE_TYPE_OUT (2) if the mode of the VWParameter is write-
only
• MODE_TYPE_IN_OUT (3) if the mode of the VWParameter is
read and write
© Copyright IBM Corporation 2011

Figure 4-17. vwParameter.getMode() F1561.0

Notes:
Additional methods on this object
The VWParameter object also has the following methods that are used in the activity for
this lesson:
public String getName()
This method returns the VWParameter name.
public Object getValue() '
public String getStringValue()
This method returns the value of this VWParameter in a String.

© Copyright IBM Corp. 2011 Unit 4. Create Work 4-21

Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
Student Notebook

Retrieve parameter values for a step element

VWFieldType.getLocalizedString(...)

public
public static
static String
String getLocalizedString
getLocalizedString
(int
(int theFieldType)
theFieldType)

• Parameters
–theFieldType – Specify an integer value associated with the field
type.
• Returns
–A String containing the localized data field type

© Copyright IBM Corporation 2011

Figure 4-18. VWFieldType.getLocalizedString(...) F1561.0

Notes:
For the theFieldType parameter of this method, the following integer values (given in
parentheses) are valid:
Attachment (FIELD_TYPE_ATTACHMENT)
Boolean (FIELD_TYPE_BOOLEAN)
Float (FIELD_TYPE_FLOAT)
Integer (FIELD_TYPE_INT)
Participant (FIELD_TYPE_PARTICIPANT)
String (FIELD_TYPE_STRING)
Time (FIELD_TYPE_TIME)
XML (FIELD_TYPE_XML)

4-22 IBM FileNet BPM 5.0: Java API Programming © Copyright IBM Corp. 2011
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
V5.4
Student Notebook

Uempty
Retrieve parameter values for a step element
VWModeType.getLocalizedString()

public
public static
static String
String getLocalizedString
getLocalizedString
(int
(int theModeType)
theModeType)

• Parameters
–theModeType – Specify an integer value associated with the mode
type.
• Returns
–The localized string representation of the mode type

© Copyright IBM Corporation 2011

Figure 4-19. VWModeType.getLocalizedString() F1561.0

Notes:
For the theModeType parameter of this method, the following integer values are valid:
- MODE_TYPE_IN
Indicates that the argument is an input parameter, which is passed by value.
- MODE_TYPE_IN_OUT
Indicates that the argument is an input/output parameter, which is passed by reference.
- MODE_TYPE_OUT
Indicates that the argument is an output parameter, which is passed by reference.

© Copyright IBM Corp. 2011 Unit 4. Create Work 4-23

Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
Student Notebook

Retrieve parameter values for a step element

vwParameter.getStringValue()

public
public String
String getStringValue()
getStringValue()

• Parameters
–None
• Returns
–The value of this parameter
• Notes
–This method converts the value of this parameter to a string.

© Copyright IBM Corporation 2011

Figure 4-20. vwParameter.getStringValue() F1561.0

Notes:

4-24 IBM FileNet BPM 5.0: Java API Programming © Copyright IBM Corp. 2011
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
V5.4
Student Notebook

Uempty
Retrieve parameter values for a step element
vwStepElement.getStepResponses()

public
public String[]
String[] getStepResponses()
getStepResponses()

• Parameters
–None
• Returns
–The available responses for the current step in String array
–Null if no responses exist

© Copyright IBM Corporation 2011

Figure 4-21. vwStepElement.getStepResponses() F1561.0

Notes:

© Copyright IBM Corp. 2011 Unit 4. Create Work 4-25

Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
Student Notebook

Retrieve parameter values for a step element

Sample code to retrieve step element fields

• Retrieve the VW step element name and description.

System.out.println("Step
System.out.println("Step Name:
Name:
"+stepElement.getStepName());
"+stepElement.getStepName());
System.out.println("Step
System.out.println("Step Description:
Description:
"+stepElement.getStepDescription());
"+stepElement.getStepDescription());
• Retrieve the VW step element responses.
String[]
String[] myResponses
myResponses ==
stepElement.getStepResponses();
stepElement.getStepResponses();
if(myResponses
if(myResponses !=!= null){
null){
int
int len
len == myResponses.length;
myResponses.length;
for(int
for(int jj == 0;
0; jj << len;
len; j++
j++ ))
System.out.println(myResponses[j]);
System.out.println(myResponses[j]);
}}

© Copyright IBM Corporation 2011

Figure 4-22. Sample code to retrieve step element fields F1561.0

Notes:

4-26 IBM FileNet BPM 5.0: Java API Programming © Copyright IBM Corp. 2011
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
V5.4
Student Notebook

Uempty
Retrieve parameter values for a step element
Sample code to retrieve parameter values
• Retrieve the user- and system-defined parameter values.
VWStepElement
VWStepElement stepElement;
stepElement;
VWParameter[]
VWParameter[] parameters
parameters == stepElement.
stepElement.
getParameters(VWFieldType.ALL_FIELD_TYPES,
getParameters(VWFieldType.ALL_FIELD_TYPES,
VWStepElement.FIELD_USER_AND_SYSTEM_DEFINED);
VWStepElement.FIELD_USER_AND_SYSTEM_DEFINED);
• Retrieve name, data type, read and write mode, value for each
parameter.
if(parameters
if(parameters !=
!= null){
null){
for
for (int
(int i=0;
i=0; i<parameters.length;
i<parameters.length; i++){
i++){
parameterName = parameters[i].getName();
parameterName = parameters[i].getName();
parameterType
parameterType == VWFieldType.getLocalizedString
VWFieldType.getLocalizedString
(parameters[i].getFieldType());
(parameters[i].getFieldType());
parameterMode
parameterMode == VWModeType.getLocalizedString
VWModeType.getLocalizedString
(parameters[i].getMode());
(parameters[i].getMode());
parameterValue
parameterValue == parameters[i].getStringValue();
parameters[i].getStringValue();
© Copyright IBM Corporation 2011

Figure 4-23. Sample code to retrieve parameter values F1561.0

Notes:

© Copyright IBM Corp. 2011 Unit 4. Create Work 4-27

Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
Student Notebook

Retrieve parameter values for a step element

Demonstrations
• Retrieve parameters values for a step.
–Explore the code sample.
–Run the solution code.
–Observe the results.

© Copyright IBM Corporation 2011

Figure 4-24. Demonstrations F1561.0

Notes:
Demonstration notes
1. Start Eclipse and open the BPMJavaAPISolution project.
2. Review the code for the getParametersEDU(…) method in the CreateWorkEDU.java
file.
3. This method is called inside the launchEDU(…) method.
4. Run the code and verify the results as instructed in the “Create Work” unit in the
Student Exercises.

4-28 IBM FileNet BPM 5.0: Java API Programming © Copyright IBM Corp. 2011
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
V5.4
Student Notebook

Uempty
Retrieve parameter values for a step element
Activities
In your Student Exercises
• Unit: Create work
• Lesson: Retrieve parameter values for a step element
• Activities:
– Retrieve parameters values for a step.

© Copyright IBM Corporation 2011

Figure 4-25. Activities F1561.0

Notes:
Use your Student Exercises to perform the activities listed.

© Copyright IBM Corp. 2011 Unit 4. Create Work 4-29

Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
Student Notebook

4-30 IBM FileNet BPM 5.0: Java API Programming © Copyright IBM Corp. 2011
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
V5.4
Student Notebook

Uempty Lesson 4.3. Set parameter values for a step element

© Copyright IBM Corp. 2011 Unit 4. Create Work 4-31

Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
Student Notebook

Lesson:
Set parameter values for a step element
• Why is this lesson important to you?
–Customer order workflows contain customer data for processing. As
the programmer, you are going to write code to set parameter values
for a step element with customer data.

© Copyright IBM Corporation 2011

Figure 4-26. Lesson: Set parameter values for a step element F1561.0

Notes:

4-32 IBM FileNet BPM 5.0: Java API Programming © Copyright IBM Corp. 2011
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
V5.4
Student Notebook

Uempty
Set parameter values for a step element
Activities that you need to complete
• Set parameter values for a step element.

© Copyright IBM Corporation 2011

Figure 4-27. Activities that you need to complete F1561.0

Notes:
These are the activities that you are going to perform in this lesson.

© Copyright IBM Corp. 2011 Unit 4. Create Work 4-33

Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
Student Notebook

Set parameter values for a step element

VWParticipant class
• VWParticipant represents workflow participants who are
authorized to process a step in a workflow.
• Workflow participants get the notifications for work items in
their User Inbox.
–Workplace XT > Tasks Page
• Use this class to include a security user or group to the
workflow.
–User or group name can be one of the following:
• "Short" (logon) name
• Distinguished name (DN)
• Display name (configurable)

© Copyright IBM Corporation 2011

Figure 4-28. VWParticipant class F1561.0

Notes:

4-34 IBM FileNet BPM 5.0: Java API Programming © Copyright IBM Corp. 2011
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
V5.4
Student Notebook

Uempty
Set parameter values for a step element
VWAttachment class
• Represents any custom object, document, or folder object from
a library that is attached to the workflow
• Supported libraries:
– Content Engine, Image Services (IDMIS), Content Services (IDMSDS)
• Use this class to access attachment used in a workflow
process:
– Identity of the attachment
– Associated library or object store
– Type and Document ID
– Version series
• When you retrieve a VWattachment in a String, the output
value is in this format:
– Attachment Name|Attachment Description|Attachment
Type|LibraryType|LibraryName|Document Id|VersionId
– Null attachment has a string value of “||0|0||”

© Copyright IBM Corporation 2011

Figure 4-29. VWAttachment class F1561.0

Notes:
The VWAttachment.toString() method gets the String representation of a VWAttachment
object associated with a document contained in library or object store.
The String contains seven elements. Each element is delimited by the SEPARATOR (|)
character. The String elements are as follows:
- Attachment name
- Attachment description
- Attachment type
- Type of library or object store that has the attachment
- Name of the library or object store that has the attachment
- Attachment ID
- Version (optional), if the attachment is a document or stored search.

© Copyright IBM Corp. 2011 Unit 4. Create Work 4-35

Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
Student Notebook

Set parameter values for a step element

Steps to set parameters values
1. Check to see if the parameter is read-only.
vwParameter.getMode
vwParameter.getMode()==VWModeType.MODE_TYPE_IN
()==VWModeType.MODE_TYPE_IN

2. If the parameter is editable, switch through each data type.

switch(vwParameter.getFieldType())
switch(vwParameter.getFieldType())
3. For each data type, check to see whether the parameter is
single or an array.
case
case VWFieldType.FIELD_TYPE_STRING
VWFieldType.FIELD_TYPE_STRING
If
If vwParameter.isArray()
vwParameter.isArray()

4. Set the value for the parameter.

vwStepElement.setParameterValue(…)
vwStepElement.setParameterValue(…)

5. Set the value for the system-defined Response parameter.

vwStepElement.setSelectedResponse(…)
vwStepElement.setSelectedResponse(…)
© Copyright IBM Corporation 2011

Figure 4-30. Steps to set parameters values F1561.0

Notes:

4-36 IBM FileNet BPM 5.0: Java API Programming © Copyright IBM Corp. 2011
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
V5.4
Student Notebook

Uempty
Set parameter values for a step element
Steps to set VWParticipant value
1. Instantiate a new VWParticipant array.
case
case VWFieldType.FIELD_TYPE_PARTICIPANT:
VWFieldType.FIELD_TYPE_PARTICIPANT:
VWParticipant[]
VWParticipant[] tempPart
tempPart == new
new VWParticipant[1];
VWParticipant[1];

2. Set the participant name.

vwParticipant[0].setParticipantName(…)
vwParticipant[0].setParticipantName(…)

3. Set the parameter value.

vwStepElement.setParameterValue(…)
vwStepElement.setParameterValue(…)

© Copyright IBM Corporation 2011

Figure 4-31. Steps to set VWParticipant value F1561.0

Notes:

© Copyright IBM Corp. 2011 Unit 4. Create Work 4-37

Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
Student Notebook

Set parameter values for a step element

Steps to set VWAttachment value (1)

1. Get the value for the VWAttachment.

case
case VWFieldType.FIELD_TYPE_ATTACHMENT:
VWFieldType.FIELD_TYPE_ATTACHMENT:
(vwAttachment)parameters[i].getValue()
(vwAttachment)parameters[i].getValue()
2. Set the attachment name.
vwAttachment.setAttachmentName(…)
vwAttachment.setAttachmentName(…)

3. Set the attachment description.

vwAttachment.setAttachmentDescription(…)
vwAttachment.setAttachmentDescription(…)

4. Set the object type.

vwAttachment.setType(…)
vwAttachment.setType(…)

© Copyright IBM Corporation 2011

Figure 4-32. Steps to set VWAttachment value (1) F1561.0

Notes:

4-38 IBM FileNet BPM 5.0: Java API Programming © Copyright IBM Corp. 2011
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
V5.4
Student Notebook

Uempty
Set parameter values for a step element
Steps to set VWAttachment value (2)

5. Set the library type and name.

vwAttachment.setLibraryType(…)
vwAttachment.setLibraryType(…)
vwAttachment.setLibraryName(…)
vwAttachment.setLibraryName(…)

6. Set the document Id and version.

vwAttachment.setId(…)
vwAttachment.setId(…)
vwAttachment.setVersion(…)
vwAttachment.setVersion(…)

7. Set the parameter value.

vwStepElement.setParameterValue(…)
vwStepElement.setParameterValue(…)

© Copyright IBM Corporation 2011

Figure 4-33. Steps to set VWAttachment value (2) F1561.0

Notes:

© Copyright IBM Corp. 2011 Unit 4. Create Work 4-39

Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
Student Notebook

Set parameter values for a step element

vwParameter.isArray()

public
public boolean
boolean isArray()
isArray()

• Parameters
–None
• Returns
–A Boolean value:
• True if the parameter is an array
• Otherwise, false

© Copyright IBM Corporation 2011

Figure 4-34. vwParameter.isArray() F1561.0

Notes:

4-40 IBM FileNet BPM 5.0: Java API Programming © Copyright IBM Corp. 2011
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
V5.4
Student Notebook

Uempty
Set parameter values for a step element
vwStepElement.setParameterValue(...)

public
public void
void setParameterValue
setParameterValue
(String
(String parameterName,
parameterName,
Object parameterValue,
Object parameterValue,
boolean
boolean compareValue)
compareValue)

• Parameters
–parameterName – Specify the name of the parameter for which the
value is to be set.
–parameterValue – Specify the object containing the value being set
in the specified parameter.
–compareValue – Specify a Boolean value:
• True to set only the changed values
• False to set all values

© Copyright IBM Corporation 2011

Figure 4-35. vwStepElement.setParameterValue(...) F1561.0

Notes:
This method sets a value for a specified parameter.
Step element parameter with VWModeType.MODE_TYPE_IN are read-only.
You can modify only those step element parameters with the following modes:
VWModeType.MODE_TYPE_OUT
VWModeType.MODE_TYPE_IN_OUT

© Copyright IBM Corp. 2011 Unit 4. Create Work 4-41

Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
Student Notebook

Set parameter values for a step element

vwParticipant.setParticipantName(...)

Public
Public void
void setParticipantName
setParticipantName
(String
(String theParticipantName)
theParticipantName)
• Parameters
–theParticipantName – Specify the “short” or “logon” name of a
participant user or group.

© Copyright IBM Corporation 2011

Figure 4-36. vwParticipant.setParticipantName(...) F1561.0

Notes:

4-42 IBM FileNet BPM 5.0: Java API Programming © Copyright IBM Corp. 2011
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
V5.4
Student Notebook

Uempty
Set parameter values for a step element
vwStepElement.setSelectedResponse(...)

public
public void
void setSelectedResponse
setSelectedResponse
(String
(String response)
response)

• Parameters
–response – Specify the response that is selected for this step.

© Copyright IBM Corporation 2011

Figure 4-37. vwStepElement.setSelectedResponse(...) F1561.0

Notes:

© Copyright IBM Corp. 2011 Unit 4. Create Work 4-43

Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
Student Notebook

Set parameter values for a step element

vwAttachment.setAttachmentName(...)

public
public void
void setAttachmentName(
setAttachmentName(
String
String theAttachmentName)
theAttachmentName)

• Parameters
–theAttachmentName – Specify a name for the attachment in a
String.
• Notes
–You cannot use the SEPARATOR (|) character, which is reserved for
internal use.

© Copyright IBM Corporation 2011

Figure 4-38. vwAttachment.setAttachmentName(...) F1561.0

Notes:

4-44 IBM FileNet BPM 5.0: Java API Programming © Copyright IBM Corp. 2011
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
V5.4
Student Notebook

Uempty
Set parameter values for a step element
vwAttachment.setType(...)

public
public void
void setType(int
setType(int theAttachmentType)
theAttachmentType)

• Parameters
–theAttachmentType – Specify the type of the associated attachment
as an integer.
• Notes
–Examples of types and the values for the constants:
• ATTACHMENT_TYPE_CUSTOM_OBJECT(6)
• ATTACHMENT_TYPE_DOCUMENT (3)
• ATTACHMENT_TYPE_FOLDER (2)
• ATTACHMENT_TYPE_LIBRARY (1)
• ATTACHMENT_TYPE_UNDEFINED (0)
• ATTACHMENT_TYPE_URL (5)

© Copyright IBM Corporation 2011

Figure 4-39. vwAttachment.setType(...) F1561.0

Notes:

© Copyright IBM Corp. 2011 Unit 4. Create Work 4-45

Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
Student Notebook

Set parameter values for a step element

vwAttachment.setLibraryType(...)

public
public void
void setLibraryType(int
setLibraryType(int theLibraryType)
theLibraryType)

• Parameters
–theLibraryType – Specify the type of the new library or object store
type of the attachment as an integer.
• Notes
–Examples of types and the values for the constants:
• LIBRARY_TYPE_CONTENT_ENGINE(3)
• LIBRARY_TYPE_UNDEFINED (0)

© Copyright IBM Corporation 2011

Figure 4-40. vwAttachment.setLibraryType(...) F1561.0

Notes:

4-46 IBM FileNet BPM 5.0: Java API Programming © Copyright IBM Corp. 2011
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
V5.4
Student Notebook

Uempty
Set parameter values for a step element
vwAttachment.setLibraryName(...)

public
public void
void setLibraryName(int
setLibraryName(int theLibraryName)
theLibraryName)

• Parameters
–theLibraryName – Specify the value to set as the library or object
store name in a String
• Notes
–You cannot use the SEPARATOR (|) character, which is reserved for
internal use.
–Library and object store names conform to the database naming
convention rules for your database.
• Name can be up to 64 characters long
• Name cannot contain any of the following characters: \ / : * ? " < > |

© Copyright IBM Corporation 2011

Figure 4-41. vwAttachment.setLibraryName(...) F1561.0

Notes:

© Copyright IBM Corp. 2011 Unit 4. Create Work 4-47

Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
Student Notebook

Set parameter values for a step element

vwAttachment.setId(...)

public
public void
void setId(String
setId(String theId)
theId)

• Parameters
–theId – Specify the version series GUID
• Notes
–You cannot include the SEPARATOR (|) character, which is
reserved for internal use.

© Copyright IBM Corporation 2011

Figure 4-42. vwAttachment.setId(...) F1561.0

Notes:

4-48 IBM FileNet BPM 5.0: Java API Programming © Copyright IBM Corp. 2011
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
V5.4
Student Notebook

Uempty
Set parameter values for a step element
vwAttachment.setVersion(...)

public
public void
void setVersion(String
setVersion(String theVersion)
theVersion)

• Parameters
–theVersion – Specify the value for the version for the attachment in a
String.
• -1 sets the most current released version.
• Empty string sets the most current version.

© Copyright IBM Corporation 2011

Figure 4-43. vwAttachment.setVersion(...) F1561.0

Notes:

© Copyright IBM Corp. 2011 Unit 4. Create Work 4-49

Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
Student Notebook

Set parameter values for a step element

Sample code to set parameter values
VWParameter[]
VWParameter[] parameters
parameters ==
stepElement.getParameters(VWFieldType.ALL_FIELD_TYP
stepElement.getParameters(VWFieldType.ALL_FIELD_TYP
ES,
ES, VWStepElement.FIELD_USER_AND_SYSTEM_DEFINED);
VWStepElement.FIELD_USER_AND_SYSTEM_DEFINED);
if
if (parameters
(parameters != != null){
null){
for
for (int
(int i=0;
i=0; i<parameters.length;
i<parameters.length; i++){
i++){
parameterName
parameterName == parameters[i].getName();
parameters[i].getName();
if(parameters[i].getMode()==
if(parameters[i].getMode()==
VWModeType.MODE_TYPE_IN)
VWModeType.MODE_TYPE_IN) {{
System.out.println("Read
System.out.println("Read Only.");
Only.");
}}
switch(parameters[i].getFieldType())
switch(parameters[i].getFieldType())
case
case VWFieldType.FIELD_TYPE_STRING:
VWFieldType.FIELD_TYPE_STRING:
if
if (parameters[i].isArray())
(parameters[i].isArray()) {{
stepElement.setParameterValue
stepElement.setParameterValue
(parameterName,value,true);
(parameterName,value,true);
}} ...
...
© Copyright IBM Corporation 2011

Figure 4-44. Sample code to set parameter values F1561.0

Notes:

4-50 IBM FileNet BPM 5.0: Java API Programming © Copyright IBM Corp. 2011
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
V5.4
Student Notebook

Uempty
Set parameter values for a step element
Sample code to set VWParticipants value

case
case VWFieldType.FIELD_TYPE_PARTICIPANT:
VWFieldType.FIELD_TYPE_PARTICIPANT:
if
if (parameters[i].isArray()){
(parameters[i].isArray()){
VWParticipant[]
VWParticipant[] tempPart
tempPart == new
new
VWParticipant[1];
VWParticipant[1];
for
for (int
(int j=0;j<tempPartA.length;j++){
j=0;j<tempPartA.length;j++){
tempPartA[j]
tempPartA[j] == new
new VWParticipant();
VWParticipant();
}}
String tempStr == “P8Admin”;
String tempStr “P8Admin”;
if
if (tempStr.length()>0)
(tempStr.length()>0) {{
tempPartA[0].setParticipantName(tempStr);
tempPartA[0].setParticipantName(tempStr);
stepElement.setParameterValue(parameterName
stepElement.setParameterValue(parameterName
,tempPartA,true);
,tempPartA,true);
}}
}} …
…
© Copyright IBM Corporation 2011

Figure 4-45. Sample code to set VWParticipants value F1561.0

Notes:

© Copyright IBM Corp. 2011 Unit 4. Create Work 4-51

Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
Student Notebook

Set parameter values for a step element

Sample code to set VWAttachment value
case
case VWFieldType.FIELD_TYPE_ATTACHMENT:
VWFieldType.FIELD_TYPE_ATTACHMENT:
VWAttachment
VWAttachment tempAtt
tempAtt == (VWAttachment)
(VWAttachment)
parameters[i].getValue();
parameters[i].getValue();
tempAtt.setAttachmentName("NewDocument");
tempAtt.setAttachmentName("NewDocument");
tempAtt.setAttachmentDescription("A
tempAtt.setAttachmentDescription("A document
document added
added
programmatically");
programmatically");
tempAtt.setType(VWAttachmentType.
tempAtt.setType(VWAttachmentType.
ATTACHMENT_TYPE_DOCUMENT);
ATTACHMENT_TYPE_DOCUMENT);
tempAtt.setLibraryType(VWLibraryType.
tempAtt.setLibraryType(VWLibraryType.
LIBRARY_TYPE_CONTENT_ENGINE);
LIBRARY_TYPE_CONTENT_ENGINE);
tempAtt.setLibraryName(“LoanProcess");
tempAtt.setLibraryName(“LoanProcess");
tempAtt.setId("{{D1345162-621A-44E3-84C5-
tempAtt.setId("{{D1345162-621A-44E3-84C5-
8137FD0B587F}}");
8137FD0B587F}}");
tempAtt.setVersion("-1");
tempAtt.setVersion("-1");
stepElement.setParameterValue(parameterName,
stepElement.setParameterValue(parameterName,
tempAtt,true);
tempAtt,true);

© Copyright IBM Corporation 2011

Figure 4-46. Sample code to set VWAttachment value F1561.0

Notes:

4-52 IBM FileNet BPM 5.0: Java API Programming © Copyright IBM Corp. 2011
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
V5.4
Student Notebook

Uempty
Set parameter values for a step element
Sample code to set response parameter value

• Set the value for the system-defined response parameter.

String[]
String[] myResponses
myResponses ==
stepElement.getStepResponses();
stepElement.getStepResponses();
if(myResponses
if(myResponses !=
!= null)
null)
{{
stepElement.setSelectedResponse(myResponses[0]);
stepElement.setSelectedResponse(myResponses[0]);
}}

© Copyright IBM Corporation 2011

Figure 4-47. Sample code to set response parameter value F1561.0

Notes:

© Copyright IBM Corp. 2011 Unit 4. Create Work 4-53

Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
Student Notebook

Set parameter values for a step element

Demonstrations
• Set parameter values for a step element.
–Explore the code sample.
–Run the solution code.
–Observe the results.

© Copyright IBM Corporation 2011

Figure 4-48. Demonstrations F1561.0

Notes:
Demonstration notes
1. Start Eclipse and open the BPMJavaAPISolution project.
2. Review the code for the setParametersEDU(…) method in the CreateWorkEDU.java
file.
3. This method is called inside the launchEDU(…) method.
4. Run the code and verify the results as instructed in the “Create Work” unit in the
Student Exercises book.

4-54 IBM FileNet BPM 5.0: Java API Programming © Copyright IBM Corp. 2011
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
V5.4
Student Notebook

Uempty
Set parameter values for a step element
Activities
In your Student Exercises
• Unit: Create work
• Lesson: Set parameter values for a step element
• Activities:
– Set parameter values for a step element.

© Copyright IBM Corporation 2011

Figure 4-49. Activities F1561.0

Notes:
Use your Student Exercises to perform the activities listed.

© Copyright IBM Corp. 2011 Unit 4. Create Work 4-55

Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
Student Notebook

4-56 IBM FileNet BPM 5.0: Java API Programming © Copyright IBM Corp. 2011
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
V5.4
Student Notebook

Uempty Lesson 4.4. Automatically launch a workflow

© Copyright IBM Corp. 2011 Unit 4. Create Work 4-57

Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
Student Notebook

Lesson:
Automatically launch a workflow
• Why is this lesson important to you?
–When a customer orders a product online, you want a specified
workflow to be automatically launched to process that order. As the
programmer, you are going to work with your Administrator to set up
a workflow subscription to automatically launch a workflow.
–The product development team uses an entry template to create draft
documents. They want to launch a workflow to start the review
process every time a draft is added. As their programmer, you are
going to work with your Administrator to set up an entry template to
automatically launch a workflow.

© Copyright IBM Corporation 2011

Figure 4-50. Lesson: Automatically launch a workflow F1561.0

Notes:

4-58 IBM FileNet BPM 5.0: Java API Programming © Copyright IBM Corp. 2011
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
V5.4
Student Notebook

Uempty
Automatically launch a workflow
Activities that you need to complete
• Automatically launch a workflow using a subscription.
• Automatically launch a workflow using an entry template
(optional).

© Copyright IBM Corporation 2011

Figure 4-51. Activities that you need to complete F1561.0

Notes:

© Copyright IBM Corp. 2011 Unit 4. Create Work 4-59

Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
Student Notebook

Automatically launch a workflow

Workflow subscription
• A subscription launches a workflow in response to trigger
events
–Trigger events occur on an associated document, folder, or custom
object on the Content Engine.
• Tools available to create a workflow subscription:
–IBM FileNet Workplace XT (preferred)
–Content Engine Enterprise Manager
• Assign workflow subscriptions to the following:
–Individual Content Engine objects
–An object class
• After class assignment, the workflow subscription is automatically assigned to
each new object of that class.

© Copyright IBM Corporation 2011

Figure 4-52. Workflow subscription F1561.0

Notes:
Help path
• IBM FileNet P8 Version 5.0 Information Center > Administering IBM FileNet P8 >
Administering Content Engine > Events and subscriptions > Concepts
Subscription Types
• General Subscription: The subscription results in a general event action such as an
email notification.
• Workflow Subscription: A workflow is automatically launched when an event occurs.
This unit presents information only on Workflow subscriptions. General subscriptions are
presented in the Content Engine Java API programming course.
Use Workplace XT to create workflow subscriptions for the following reasons:
• Workplace XT allows non-administrators to create subscriptions.
• Workplace XT is a tool that is easier to use for mapping properties.

4-60 IBM FileNet BPM 5.0: Java API Programming © Copyright IBM Corp. 2011
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
V5.4
Student Notebook

Uempty
Automatically launch a workflow
Steps to create a workflow subscription
1. Navigate to Workplace XT > Tools > Advanced Tools
> Workflow Subscriptions > Add
– Add Workflow Subscription Wizard opens.
2. Select the target object class for the trigger event.
3. Select the workflow to be launched.
4. Specify a name and description for the Workflow
Subscription.
5. Define property-based conditions for launching a
workflow.
6. Map any workflow data fields to object properties.
7. Set security on the workflow subscription.
© Copyright IBM Corporation 2011

Figure 4-53. Steps to create a workflow subscription F1561.0

Notes:
Help path
• IBM FileNet P8 Version 5.0 Information Center > Working with documents > Working
with documents with Workplace XT > Tools > Workflow subscriptions > Workflow
Subscription wizard

© Copyright IBM Corp. 2011 Unit 4. Create Work 4-61

Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
Student Notebook

Automatically launch a workflow

Select the target and define the conditions
• Select the object store containing the objects and workflow
• Select the object class
–A Content Engine class: Folders, Documents, or Custom Objects
–Or a subclass of one of these classes
• Define property-based conditions for launching the workflow
–For example, launch a workflow only if
• The document was created by a specific user
• A particular property is set to a specific value

© Copyright IBM Corporation 2011

Figure 4-54. Select the target and define the conditions F1561.0

Notes:
Help path
• IBM FileNet P8 Version 5.0 Information Center > Working with documents > Working
with documents with Workplace XT > Tools > Workflow subscriptions > Workflow
Subscription wizard > Selecting target class

4-62 IBM FileNet BPM 5.0: Java API Programming © Copyright IBM Corp. 2011
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
V5.4
Student Notebook

Uempty
Automatically launch a workflow
Map workflow data fields
• Map workflow data fields to object properties:
–Example:
• A workflow has a data field for Employee Name that must be
mapped to the Creator property of the object.
• When the workflow is launched, the data field will have the value
from the Content Engine object property.
• Points to consider for property mapping
–Map properties only to data fields with the same data type.
–If the value of a property is another object (object value
property), it cannot be mapped to a data field.
–GUIDs cannot be mapped to data fields.

© Copyright IBM Corporation 2011

Figure 4-55. Map workflow data fields F1561.0

Notes:
Help path
• IBM FileNet P8 Version 5.0 Information Center > Working with documents > Working
with documents with Workplace XT > Tools > Workflow subscriptions > Workflow
Subscription wizard > Setting property mapping

© Copyright IBM Corp. 2011 Unit 4. Create Work 4-63

Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
Student Notebook

Automatically launch a workflow

Entry templates
• Entry templates
–Are user tools for adding folders, custom objects, and
documents to an object store
–Can include preselected options and default values
–Can include hidden, read-only, and editable fields and
values
• Advantages
–Save users time by reducing user steps
–Reduce user error by preselected choices
–Can automatically launch workflows
–Can define document approval workflows
–Can be used with IBM FileNet Application Integration
© Copyright IBM Corporation 2011

Figure 4-56. Entry templates F1561.0

Notes:
Help paths
• IBM FileNet P8 Version 5.0 Information Center > Working with documents > Working
with documents with Workplace XT > Work with entry templates
• IBM FileNet P8 Version 5.0 Information Center > Working with documents > Working
with documents with Workplace XT > Tools > Entry Template Designer > Entry
templates for new items
Entry templates automate much of the document entry process by allowing the entry
template builder to preselect destination folders, property values, and security settings for
the end user.

4-64 IBM FileNet BPM 5.0: Java API Programming © Copyright IBM Corp. 2011
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
V5.4
Student Notebook

Uempty
Automatically launch a workflow
Entry Template Designer wizard
Section Defines
“Define Template”
1. Select Folder • Defaults for item to be added
2. Select Class
3. Set Properties • Options viewed by the end user
4. Set Security • Selections and entries that user can make
“Define Workflow” • Select an existing workflow or
define a new workflow
5. Select Workflow
6. Set Properties • Select automatic launch or prompt user

“Save Template”
7. Select Folder • Entry template name and description
8. Set Properties
9. Set Security
• Entry template location and security
© Copyright IBM Corporation 2011

Figure 4-57. Entry Template Designer wizard F1561.0

Notes:
The table in this page lists the different sections in the Entry Template Designer wizard and
describes each section.

Help paths
• IBM FileNet P8 Version 5.0 Information Center > Working with documents > Working
with documents with Workplace XT > Work with entry templates > Use an entry
template
• IBM FileNet P8 Version 5.0 Information Center > Working with documents > Working
with documents with Workplace XT > Tools > Entry Template Designer > Entry
templates for new items

© Copyright IBM Corp. 2011 Unit 4. Create Work 4-65

Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
Student Notebook

Automatically launch a workflow

Steps to use a document entry template
1. Open the entry template.
2. Add a document.
a. Select the folder (if the folder choice is not hidden).
b. Select or enter properties (if fields are not hidden).
c. Set its security (if the security page is not hidden).
d. Select the document being added.
3. Launch a workflow (if one is associated with the
template).
a. Review and select step participants (if the choice is not
hidden).
b. Launch the workflow (if launch is not automatic).

© Copyright IBM Corporation 2011

Figure 4-58. Steps to use a document entry template F1561.0

Notes:
Help paths
• IBM FileNet P8 Version 5.0 Information Center > Working with documents > Working
with documents with Workplace XT > Work with entry templates > Use an entry
template
• IBM FileNet P8 Version 5.0 Information Center > Working with documents > Working
with documents with Workplace XT > Working with documents > Add a document
• IBM FileNet P8 Version 5.0 Information Center > Working with documents > Working
with documents with Workplace XT > Working with tasks > Manually launch a workflow

4-66 IBM FileNet BPM 5.0: Java API Programming © Copyright IBM Corp. 2011
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
V5.4
Student Notebook

Uempty
Automatically launch a workflow
Demonstrations
• Automatically launch a workflow using a subscription.

© Copyright IBM Corporation 2011

Figure 4-59. Demonstrations F1561.0

Notes:
Demonstration notes
Create a workflow subscription and automatically launch a workflow using the instructions
for the “Automatically launch a workflow using a subscription” activity in the “Create Work”
unit in the Student Exercises.

© Copyright IBM Corp. 2011 Unit 4. Create Work 4-67

Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
Student Notebook

Automatically launch a workflow

Activities
In your Student Exercises
• Unit: Create work
• Lesson: Automatically launch a workflow
• Activities:
– Automatically launch a workflow using a subscription.
– Automatically launch a workflow using an entry template
(Optional).

© Copyright IBM Corporation 2011

Figure 4-60. Activities F1561.0

Notes:
Use your Student Exercises to perform the activities listed.

4-68 IBM FileNet BPM 5.0: Java API Programming © Copyright IBM Corp. 2011
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
V5.4
Student Notebook

Uempty Unit 5. Find Work

What this unit is about

This unit describes how to write code using Process Engine Java API
to query a roster, an Inbox and an event log and display the results.

What you should be able to do

After completing this unit, you should be able to:
• Query a roster for all elements and using a filter.
• Retrieve queues.
• Query a queue for all elements, using a filter and an index.
• Query an event log for all elements and using a filter.

How you will check your progress

• Successfully complete the activities in the Student Exercises book.

References
www.ibm.com/support/documentation/us/en (Support & downloads
page)
Note: IBM FileNet products belong to the Information Management
product set.

© Copyright IBM Corp. 2011 Unit 5. Find Work 5-1

Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
Student Notebook

Find Work
Unit lessons
This unit contains the following lessons:
• Query a roster
• Query a queue
• Query an event log

© Copyright IBM Corporation 2011

Figure 5-1. Unit lessons F1561.0

Notes:
Lessons in this unit
This unit has three lessons. After the first lesson, each lesson relies on information and
skills taught in the prior lessons. For best results, do these lessons in the sequence
presented.
Query a roster – In this lesson, you write code to query the roster to retrieve the
information for the report.
Query a queue – In this lesson, you write code to query the Inbox for the required
information.
Query an event log – In this lesson, you write code to query the event log for the required
information.

5-2 IBM FileNet BPM 5.0: Java API Programming © Copyright IBM Corp. 2011
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
V5.4
Student Notebook

Uempty Lesson 5.1. Query a roster

© Copyright IBM Corp. 2011 Unit 5. Find Work 5-3

Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
Student Notebook

Lesson:
Query a roster
• Why is this lesson important to you?
– The sales processing group of your company wants a daily report of
all orders in progress. You are going to write code to query the roster
to retrieve the information for the report.

© Copyright IBM Corporation 2011

Figure 5-2. Lesson: Query a roster F1561.0

Notes:

5-4 IBM FileNet BPM 5.0: Java API Programming © Copyright IBM Corp. 2011
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
V5.4
Student Notebook

Uempty
Query a roster
Activities that you need to complete

• Query a roster for all elements.

• Query a roster using a filter.

© Copyright IBM Corporation 2011

Figure 5-3. Activities that you need to complete F1561.0

Notes:
These are the activities that you are going to perform in this lesson.

© Copyright IBM Corp. 2011 Unit 5. Find Work 5-5

Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
Student Notebook

Query a roster
Workflow rosters
• Definition
–A workflow roster is a database structure that stores the current
location and other information about all workflows.
• Function
–Workflow rosters provide an efficient way to locate specific
workflows.
• Workflow rosters are usually called rosters.

© Copyright IBM Corporation 2011

Figure 5-4. Workflow rosters F1561.0

Notes:
Help path
• IBM FileNet P8 Version 5.0 information center > Integrating workflow into document
management > Process Configuration Console > Configure workflow rosters
A workflow roster is a collection of records that represents the work objects that an
associated work class instantiates.
The DefaultRoster is created at isolated region initialization. During normal operation of the
isolated region, the DefaultRoster contains the current location and other configurable
information about all active workflows and work items.
Additional rosters can be created if the application requires them.

5-6 IBM FileNet BPM 5.0: Java API Programming © Copyright IBM Corp. 2011
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
V5.4
Student Notebook

Uempty
Query a roster
Work objects
• Definition
–A work object is a database record that holds information about a
stage in a workflow.
• A work object consists of the following:
–A header containing exposed system fields
–Exposed data fields used by the application
–A BLOB (binary large object) holding most of the data for the work
item in a compact form
• A work object is also called a “Wob” or “work item.”

© Copyright IBM Corporation 2011

Figure 5-5. Work objects F1561.0

Notes:
A work item is a database record that consists of a header (exposed system fields),
exposed data fields (fields specified during definition of the workflow), and a BLOB (binary
large object).
The BLOB can contain all the information the work item defines in a compact binary format,
but in this compact format, the information is not easily accessible. Consequently, the work
item is a combination of binary information (in the BLOB) and exposed data fields. Exposed
data is not contained in the BLOB.
The FileNet BPM software automatically exposes some fields necessary for the operation
of the Process Engine environment in data fields called System Fields. By convention,
FileNet system fields are named F_<description>.
As a work item moves from queue to queue, the Process Engine exposes fields or
reassigns them to the BLOB, depending on the configuration of the particular queue. The
size of the BLOB varies depending on the fields that are exposed in a particular queue.

© Copyright IBM Corp. 2011 Unit 5. Find Work 5-7

Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
Student Notebook

While a work item is active, the roster maintains a record of the work item location and
status.
Significant performance degradation can occur as a result of exposing some system or
data fields in a roster. Fields that change often (such as F_OperationId, F_Comments, or
F_StepProcId) must never be exposed in a roster. Fields exposed in a roster must be
stable fields that do not change often. The reason for choosing stable fields is that rosters
are updated only when an exposed field changes or when a work item moves from server
to server. The degradation resulting from improperly exposed fields in a multiserver
environment can be significant.

5-8 IBM FileNet BPM 5.0: Java API Programming © Copyright IBM Corp. 2011
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
V5.4
Student Notebook

Uempty
Query a roster
Steps to retrieve roster work items (1)

1. Retrieve the roster to be searched and the Roster count.

vwSession.getRoster(…)
vwSession.getRoster(…)
vwRoster.fetchCount()
vwRoster.fetchCount()

2. Set the query parameters.

queryFiler
queryFiler == "F_WobNum=F_WorkFlowNumber"
"F_WobNum=F_WorkFlowNumber"
fetchType
fetchType == VWFetchType.FETCH_TYPE_ROSTER_ELEMENT
VWFetchType.FETCH_TYPE_ROSTER_ELEMENT
queryFlags
queryFlags == VWRoster.QUERY_NO_OPTIONS
VWRoster.QUERY_NO_OPTIONS

3. Perform the query.

vwRoster.createQuery(…)
vwRoster.createQuery(…)

© Copyright IBM Corporation 2011

Figure 5-6. Steps to retrieve roster work items (1) F1561.0

Notes:

© Copyright IBM Corp. 2011 Unit 5. Find Work 5-9

Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
Student Notebook

Query a roster
Steps to retrieve roster work items (2)

4. Retrieve the roster element information.

vwRosterQuery.next()
vwRosterQuery.next()
vwRosterElement.getWorkflowNumber()
vwRosterElement.getWorkflowNumber()
vwRosterElement.getWorkObjectNumber()
vwRosterElement.getWorkObjectNumber()
vwRosterElement.getFieldValue(…)
vwRosterElement.getFieldValue(…)

© Copyright IBM Corporation 2011

Figure 5-7. Steps to retrieve roster work items (2) F1561.0

Notes:

5-10 IBM FileNet BPM 5.0: Java API Programming © Copyright IBM Corp. 2011
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
V5.4
Student Notebook

Uempty
Query a roster
vwSession.getRoster(…)

public
public VWRoster
VWRoster getRoster(String
getRoster(String rosterName)
rosterName)

• Parameters
–rosterName - Specify the name of the workflow roster.
• Returns
–A VWRoster object that represents the workflow roster that is
specified by the rosterName parameter
• Notes
–Use the fetchRosterNames(...) method to get a list of the
names of all rosters within the isolated region.

© Copyright IBM Corporation 2011

Figure 5-8. vwSession.getRoster(...) F1561.0

Notes:

© Copyright IBM Corp. 2011 Unit 5. Find Work 5-11

Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
Student Notebook

Query a roster
vwRoster.fetchCount()

public
public int
int fetchCount()
fetchCount()

• Parameters
–None
• Returns
–An integer value indicating the number of work items in the roster

© Copyright IBM Corporation 2011

Figure 5-9. vwRoster.fetchCount() F1561.0

Notes:

5-12 IBM FileNet BPM 5.0: Java API Programming © Copyright IBM Corp. 2011
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
V5.4
Student Notebook

Uempty
Query a roster
vwRoster.createQuery(…)

public
public VWRosterQuery
VWRosterQuery createQuery
createQuery
(String
(String indexName,
indexName, Object[]
Object[] minValues,
minValues,
Object[]
Object[] maxValues,
maxValues, int
int queryFlags,
queryFlags,
String
String filter,
filter, Object[]
Object[] substitutionVars,
substitutionVars,
int
int fetchType)
fetchType)

• Parameters
–indexName - Specify the name of the database search index for
the queue.
–See notes for the other parameters.

• Returns
–A VWRosterQuery instance from which items are fetched by iteration
with the VWRosterQuery.next() method
© Copyright IBM Corporation 2011

Figure 5-10. vwRoster.createQuery(...) F1561.0

Notes:
Parameters
filter - An SQL WHERE clause used as a filter, and having placeholder variables that are
replaced by values in the substitutionVars parameter. The SQL WHERE clause must
contain a search field name on the left side of a Boolean operator and a placeholder
variable on the right side of the operator.
The field names are processed as SQL column names. For this reason, do not use SQL
function names as field names. The search field can be a variable, a system field, or a
user-defined field (the authored string).
When the filter parameter is processed, each placeholder variable is replaced (in
corresponding order) with a value specified in the substitutionVars parameter.
substitutionVars - An array of objects containing the values to substitute for the
placeholder variables specified in the SQL WHERE clause for the filter parameter. A
VWWorkObjectNumber object can be used here in place of F_WobNum and

© Copyright IBM Corp. 2011 Unit 5. Find Work 5-13

Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
Student Notebook

F_WorkFlowNumber. Queries to DB2 databases must use VWWorkObjectNumber

instead of F_WobNum or F_WorkFlowNumber.
fetchType - Possible element type values are one of the following:
- Work object (FETCH_TYPE_WORKOBJECT)
- Instruction element (FETCH_TYPE_INSTRUCTION_ELEMENT)
- Queue element (FETCH_TYPE_QUEUE_ELEMENT)
- Roster (FETCH_TYPE_ROSTER_ELEMENT)
- Step element (FETCH_TYPE_STEP_ELEMENT)
minValues - Specify an array of objects containing the minimum values with which to
compare the index fields.
maxValues - Specify an array of objects containing the maximum values with which to
compare the index fields.
queryFlags - An integer value that specifies the search options. Set this parameter to
refine the search for the work items specified by the search index. Use the | and +
operators to combine the flags.
The following list of Query Flags includes the Int Value in parentheses and the description:
• QUERY_GET_NO_SYSTEM_FIELDS(1024) - Return objects without system fields.
• QUERY_GET_NO_TRANSLATED_SYSTEM_FIELDS(2048) - Return objects without
translated fields.
• QUERY_MAX_VALUES_INCLUSIVE(64) - Specify the inclusion of maximum search
values.
• QUERY_MIN_VALUES_INCLUSIVE(32) - Specify the inclusion of minimum search
values.
• QUERY_NO_OPTIONS(0) - Specify no search option.
• QUERY_READ_UNWRITABLE(4) - Specify the return of Read-only work items.
• QUERY_RESOLVE_NAMES(8192)

5-14 IBM FileNet BPM 5.0: Java API Programming © Copyright IBM Corp. 2011
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
V5.4
Student Notebook

Uempty
Query a roster
vwRosterQuery.next()

public
public Object
Object next()
next()

• Parameters
–None
• Returns
–An object that represents an item of the fetch type specified in the
VWRoster.createQuery(…) method that created the current
VWRosterQuery object
–Or null, which indicates there are no more objects in the series
• Notes
–The returned object needs to be cast to the fetch type specified by
the creating VWRoster.createQuery(…) call.

© Copyright IBM Corporation 2011

Figure 5-11. vwRosterQuery.next() F1561.0

Notes:
The VWRosterQuery.next() method is used in a manner similar to the next() method of
the Iterator interface in Java 2.

© Copyright IBM Corp. 2011 Unit 5. Find Work 5-15

Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
Student Notebook

Query a roster
vwRosterElement.getWorkflowNumber()

public
public String
String getWorkflowNumber()
getWorkflowNumber()

• Parameters
–None
• Returns
–The workflow object number in String format, which corresponds to
the F_WorkFlowNumber
–Or null, if the F_WorkFlowNumber field does not exist

© Copyright IBM Corporation 2011

Figure 5-12. vwRosterElement.getWorkflowNumber() F1561.0

Notes:

5-16 IBM FileNet BPM 5.0: Java API Programming © Copyright IBM Corp. 2011
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
V5.4
Student Notebook

Uempty
Query a roster
vwRosterElement.getWorkObjectNumber()

public
public String
String getWorkObjectNumber()
getWorkObjectNumber()

• Parameters
–None
• Returns
–The work object number, which corresponds to the F_WobNum
queue field

© Copyright IBM Corporation 2011

Figure 5-13. vwRosterElement.getWorkObjectNumber() F1561.0

Notes:

© Copyright IBM Corp. 2011 Unit 5. Find Work 5-17

Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
Student Notebook

Query a roster
vwRosterElement.getFieldValue(…)

public
public Object
Object getFieldValue(String
getFieldValue(String fieldName)
fieldName)

• Parameters
–fieldName - Specify the name of the field containing the value being
retrieved.
• Returns
–The value of the specified field
• Notes
–Objects and arrays of objects must be one of the following Java
types: Integer, String, Double, Data, or Boolean.
–The field can have a null value.

© Copyright IBM Corporation 2011

Figure 5-14. vwRosterElement.getFieldValue(...) F1561.0

Notes:
Example of system defined fields:
F_StartTime
F_Subject
F_BoundUser

5-18 IBM FileNet BPM 5.0: Java API Programming © Copyright IBM Corp. 2011
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
V5.4
Student Notebook

Uempty
Query a roster
Sample code to retrieve roster items

VWRoster
VWRoster roster
roster ==
myPESession.getRoster("LoanRoster");
myPESession.getRoster("LoanRoster");
System.out.println("Workflow
System.out.println("Workflow Count:
Count: "" ++
roster.fetchCount());
roster.fetchCount());
int
int queryFlags
queryFlags == VWRoster.QUERY_NO_OPTIONS;
VWRoster.QUERY_NO_OPTIONS;
String
String queryFilter
queryFilter ==
"F_WobNum=F_WorkFlowNumber";
"F_WobNum=F_WorkFlowNumber";
int
int fetchType
fetchType ==
VWFetchType.FETCH_TYPE_ROSTER_ELEMENT;
VWFetchType.FETCH_TYPE_ROSTER_ELEMENT;
VWRosterQuery
VWRosterQuery query
query ==
roster.createQuery(null,null,null,
roster.createQuery(null,null,null,
queryFlag,queryFilter,null,fetchType);
queryFlag,queryFilter,null,fetchType);
VWRosterElement
VWRosterElement rosterItem
rosterItem ==
(VWRosterElement)query.next();
(VWRosterElement)query.next();
...
...
© Copyright IBM Corporation 2011

Figure 5-15. Sample code to retrieve roster items F1561.0

Notes:
The sample code in the slide assumes that a VWSession is already established and
assigned to a variable called myPESession.

© Copyright IBM Corp. 2011 Unit 5. Find Work 5-19

Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
Student Notebook

Query a roster
Sample code to display roster work items

System.out.println(
System.out.println(
"WF
"WF Number:”
Number:” ++
rosterItem.getWorkflowNumber()+
rosterItem.getWorkflowNumber()+
"WOB
"WOB Number:”
Number:” ++
rosterItem.getWorkObjectNumber()
rosterItem.getWorkObjectNumber() ++
"F_StartTime:”
"F_StartTime:” ++
rosterItem.getFieldValue("F_StartTime")+
rosterItem.getFieldValue("F_StartTime")+
"F_Subject:”
"F_Subject:” ++
rosterItem.getFieldValue("F_Subject")
rosterItem.getFieldValue("F_Subject") ++
"Loan
"Loan Id:
Id: "" ++
rosterItem.getFieldValue("loan_id") );
rosterItem.getFieldValue("loan_id") );
...
...

© Copyright IBM Corporation 2011

Figure 5-16. Sample code to display roster work items F1561.0

Notes:

5-20 IBM FileNet BPM 5.0: Java API Programming © Copyright IBM Corp. 2011
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
V5.4
Student Notebook

Uempty
Query a roster
Demonstrations
• Query a roster for all elements.
• Query a roster using a filter.
–Explore the code sample.
–Run the solution code.
–Observe the results.

© Copyright IBM Corporation 2011

Figure 5-17. Demonstrations F1561.0

Notes:
Demonstration notes - 1
1. Start Eclipse and open the BPMJavaAPISolution project.
2. Review the code for querying a roster for all elements in the queryRosterEDU (…)
method in the FindWorkEDU.java file.
3. Run the code and verify the results as instructed in the “Find Work” unit in the Student
Exercises.
Demonstration notes - 2
1. Repeat steps 2 and 3 in the demontration -1 for the code for querying the roster using a
filter.
2. Notice that exercise 3 is an alternate filter example using a date and time as a filter.
The date and time filter expression is “F_StartTime >=” + value
The filter date and time, 5/20/11 0:01 AM, must be converted to a value represented as
seconds since January 1, 1970, 00:00:00 GMT.

© Copyright IBM Corp. 2011 Unit 5. Find Work 5-21

Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
Student Notebook

This conversion is done by

Calling date = dateFormat.parse("5/20/11 0:01 AM"); convert to milliseconds
since January 1, 1970, 00:00:00 GMT.
And then calling value = date.getTime() / 1000 t convert Milliseconds to
seconds.

5-22 IBM FileNet BPM 5.0: Java API Programming © Copyright IBM Corp. 2011
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
V5.4
Student Notebook

Uempty
Query a roster
Activities
In your Student Exercises
• Unit: Find work
• Lesson: Query a roster
• Activities:
–Query a roster for all elements.
–Query a roster using a filter.

© Copyright IBM Corporation 2011

Figure 5-18. Activities F1561.0

Notes:
Use your Student Exercises to perform the activities listed.

© Copyright IBM Corp. 2011 Unit 5. Find Work 5-23

Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
Student Notebook

5-24 IBM FileNet BPM 5.0: Java API Programming © Copyright IBM Corp. 2011
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
V5.4
Student Notebook

Uempty Lesson 5.2. Query a queue

© Copyright IBM Corp. 2011 Unit 5. Find Work 5-25

Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
Student Notebook

Lesson:
Query a queue
• Why is this lesson important to you?
– Your company sales team has expressed concerns about their order
processing workload. Management wants a simple tool that allows
them to see the work that is assigned to each sales coordinator. You
are going to write code to query the Inbox for the required
information.

© Copyright IBM Corporation 2011

Figure 5-19. Lesson: Query a queue F1561.0

Notes:

5-26 IBM FileNet BPM 5.0: Java API Programming © Copyright IBM Corp. 2011
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
V5.4
Student Notebook

Uempty
Query a queue
Activities that you need to complete

• Retrieve queues.
• Query a queue for all elements.
• Query a queue using a filter.
• Query a queue using an index.

© Copyright IBM Corporation 2011

Figure 5-20. Activities that you need to complete F1561.0

Notes:
These are the activities that you are going to perform in this lesson.

© Copyright IBM Corp. 2011 Unit 5. Find Work 5-27

Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
Student Notebook

Query a queue
Steps to retrieve queue names in a given region

1. Retrieve the queue names.

vwSession.fetchQueueNames(…)
vwSession.fetchQueueNames(…)

2. Check whether the queue is component queue.

vwQueue.getIsConnectorQueue()
vwQueue.getIsConnectorQueue()

© Copyright IBM Corporation 2011

Figure 5-21. Steps to retrieve queue names in a given region F1561.0

Notes:

5-28 IBM FileNet BPM 5.0: Java API Programming © Copyright IBM Corp. 2011
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
V5.4
Student Notebook

Uempty
Query a queue
Steps to retrieve queue elements (1)

1. Retrieve the queue to be searched.

vwSession.getQueue(…)
vwSession.getQueue(…)

2. Get the total number of items in the queue.

vwQueue.fetchCount()
vwQueue.fetchCount()

3. Set the query parameters.

queryIndex
queryIndex == "F_WobNum"
"F_WobNum"
queryFlag
queryFlag == VWQueue.QUERY_NO_OPTIONS
VWQueue.QUERY_NO_OPTIONS
queryFilter
queryFilter == "F_Subject
"F_Subject like
like ‘Sara%'"
‘Sara%'"
fetchType=
fetchType=VWFetchType.FETCH_TYPE_QUEUE_ELEMENT
VWFetchType.FETCH_TYPE_QUEUE_ELEMENT

© Copyright IBM Corporation 2011

Figure 5-22. Steps to retrieve queue elements (1) F1561.0

Notes:

© Copyright IBM Corp. 2011 Unit 5. Find Work 5-29

Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
Student Notebook

Query a queue
Steps to retrieve queue elements (2)

4. Perform the query.

vwQueue.createQuery(…)
vwQueue.createQuery(…)

5. Process the results returned by the query.

vwQueueQuery.fetchCount()
vwQueueQuery.fetchCount()
vwQueueQuery.fetchCount()
vwQueueQuery.fetchCount()
vwQueueQuery.next()
vwQueueQuery.next()
vwQueueQuery.next()
vwQueueQuery.next()
vwQueueElement.getWorkflowName()
vwQueueElement.getWorkflowName()
vwQueueElement.getWorkflowName()
vwQueueElement.getWorkflowName()

© Copyright IBM Corporation 2011

Figure 5-23. Steps to retrieve queue elements (2) F1561.0

Notes:

5-30 IBM FileNet BPM 5.0: Java API Programming © Copyright IBM Corp. 2011
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
V5.4
Student Notebook

Uempty
Query a queue
Queue methods similar to roster methods
• Many queue-related methods are similar to the corresponding
roster methods.
Queue Method Roster Method

VWSession.getQueue(…) VWSession.getRoster(…)

VWQueueQuery.fetchCount() VWRosterQuery.fetchCount()

VWQueue.createQuery(…) VWRoster.createQuery(…)

VWQueueQuery.next() VWRosterQuery.next()

VWQueueElement. VWRosterElement.
getFieldValue(…) getFieldValue(…)

VWQueueElement. VWRosterElement.
getWorkflowNumber() getWorkflowNumber()
© Copyright IBM Corporation 2011

Figure 5-24. Queue methods similar to roster methods F1561.0

Notes:
The table in this page compares the methods available for Queues with that of Rosters.
The lists in the table are not exhaustive.

© Copyright IBM Corp. 2011 Unit 5. Find Work 5-31

Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
Student Notebook

Query a queue
vwSession.fetchQueueNames()

public
public String[]
String[] fetchQueueNames(int
fetchQueueNames(int
fetchFlag)
fetchFlag)
• Parameters
–fetchFlag – Specify an integer or integers corresponding to one or
more of the following queue type fields:
• QUEUE_PROCESS
• QUEUE_USER_CENTRIC
• QUEUE_SYSTEM
• QUEUE_IGNORE_SECURITY
• QUEUE_USER_CENTRIC_FOR_USER_ONLY
• Returns
–A String array of the translated queue names, if a translation source
exists. Otherwise, the authored names are returned.
© Copyright IBM Corporation 2011

Figure 5-25. vwSession.fetchQueueNames() F1561.0

Notes:
Specify multiple queue types using a bitwise OR of the fields. For example:
Retrieve a list of queue names for process queues and system queues, whether this user
has access privileges to the queues or not:
int myQueueFlags = (QUEUE_PROCESS | QUEUE_SYSTEM | QUEUE_IGNORE_SECURITY);
String[] QueueNames = null; QueueNames =
MySession.fetchQueueNames(myQueueFlags);
Note: Authored name is the original name used to create a queue.
If there are problems with communications, or server or connection problems, a
VWException is thrown.

5-32 IBM FileNet BPM 5.0: Java API Programming © Copyright IBM Corp. 2011
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
V5.4
Student Notebook

Uempty
Query a queue
vwQueue.getIsConnectorQueue()

public
public boolean
boolean getIsConnectorQueue()
getIsConnectorQueue()

• Parameters
– None
• Returns
–A boolean value
– True if this queue is a connector queue. Otherwise, false.
• Notes
–This method indicates whether or not this queue is a connector
queue.
–This method throws VWException.

© Copyright IBM Corporation 2011

Figure 5-26. vwQueue.getIsConnectorQueue() F1561.0

Notes:

© Copyright IBM Corp. 2011 Unit 5. Find Work 5-33

Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
Student Notebook

Query a queue
vwQueue.fetchCount()

public
public int
int fetchCount()
fetchCount()

• Parameters
–None
• Returns
–An integer value indicating the current depth of the queue

© Copyright IBM Corporation 2011

Figure 5-27. vwQueue.fetchCount() F1561.0

Notes:

5-34 IBM FileNet BPM 5.0: Java API Programming © Copyright IBM Corp. 2011
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
V5.4
Student Notebook

Uempty
Query a queue
vwQueue.createQuery(…)

public
public VWQueueQuery
VWQueueQuery createQuery
createQuery
(String
(String indexName,
indexName, Object[]
Object[] minValues,
minValues,
Object[]
Object[] maxValues,
maxValues, int
int queryFlags,
queryFlags,
String
String filter,
filter, Object[]
Object[] substitutionVars,
substitutionVars,
int fetchType)
int fetchType)

• Parameters
–indexName - Specify the name of the database search index for the
queue.
–See the notes for all the parameters used.
• Returns
–A VWQueueQuery object for the queue from which items are fetched
with the VWQueueQuery.next() method.

© Copyright IBM Corporation 2011

Figure 5-28. vwQueue.createQuery(...) F1561.0

Notes:
Parameters
queryFlags - Specify a value for the search options.
filter - Specify an SQL WHERE clause to be used as a filter, which has placeholder
variables that are replaced by values in the substitutionVars parameter.
substitutionVars - Specify an array of objects containing the values to substitute for the
placeholder variables specified in the filter parameter.
fetchType - Specify a value associated with the element type to be retrieved using the
object returned by VWRosterQuery.
indexName - Enter either the name assigned to the index at the Configuration Console or
a system field name.
An index assigned through the Configuration Console can be a user or system-defined
search field, or it can be both.
The standard system search fields for queues are as follows:

© Copyright IBM Corp. 2011 Unit 5. Find Work 5-35

Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
Student Notebook

F_WobNum: work item number of type byte[]

For Microsoft SQL, use this syntax: 0x
For DB2, use this syntax: x''
For Oracle, use this syntax: ''
F_SortRule: predefined as F_Locked (type integer)
minValues - Specify an array of objects containing the minimum values with which to
compare the index fields.
maxValues - Specify an array of objects containing the maximum values with which to
compare the index fields.
minValues and maxValues - Array element data types must match the corresponding
data types in the search index. If the number of minValues and maxValues array elements
is smaller than the number of search fields, the unmatched search fields are ignored. The
array elements must be of a Java type that corresponds to a Process Engine type (integer,
float, Boolean, or string). Strings must be the authored strings.

5-36 IBM FileNet BPM 5.0: Java API Programming © Copyright IBM Corp. 2011
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
V5.4
Student Notebook

Uempty
Query a queue
vwQueueQuery.fetchCount()

public
public int
int fetchCount()
fetchCount()

• Parameters
–None
• Returns
–An integer value indicating the number of records that could be
retrieved in the queue, using this VWQueueQuery object queue.
• Notes
–This method gives the total number of items in the queue that
matches the condition of the query.
–Results are approximate because the record set may change before
the query returns.

© Copyright IBM Corporation 2011

Figure 5-29. vwQueueQuery.fetchCount() F1561.0

Notes:

© Copyright IBM Corp. 2011 Unit 5. Find Work 5-37

Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
Student Notebook

Query a queue
vwQueueElement.getWorkflowName()
public
public String
String getWorkflowName()
getWorkflowName()

• Parameters
–None
• Returns
–The name of the work class from which the workflow object logged
was instantiated

© Copyright IBM Corporation 2011

Figure 5-30. vwQueueElement.getWorkflowName() F1561.0

Notes:

5-38 IBM FileNet BPM 5.0: Java API Programming © Copyright IBM Corp. 2011
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
V5.4
Student Notebook

Uempty
Query a queue
Sample code to retrieve queues

String
String queueNames[]=
queueNames[]= myPESession.
myPESession.
fetchQueueNames(VWSession.QUEUE_PROCESS);
fetchQueueNames(VWSession.QUEUE_PROCESS);
for
for (int
(int ii == 0;
0; ii << queueNames.length;
queueNames.length; i++){
i++){
VWQueue
VWQueue queue
queue ==
vwSession.getQueue(queueNames[i]);
vwSession.getQueue(queueNames[i]);
if
if (queue.getIsConnectorQueue())
(queue.getIsConnectorQueue())
System.out.print("Component
System.out.print("Component queue:
queue: ");
");

System.out.println(queueNames[i]);
System.out.println(queueNames[i]);
}}

© Copyright IBM Corporation 2011

Figure 5-31. Sample code to retrieve queues F1561.0

Notes:
The sample code in this page assumes that a VWSession is already established and
assigned to a variable called myPESession.

© Copyright IBM Corp. 2011 Unit 5. Find Work 5-39

Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
Student Notebook

Query a queue
Sample code to query a queue

VWQueue
VWQueue queue
queue == mySession.getQueue("Inbox");
mySession.getQueue("Inbox");
String
String queryIndex
queryIndex == "F_WobNum";
"F_WobNum";
Object[]
Object[] queryMin[0]
queryMin[0] == wob;
wob;
Object[]
Object[] queryMax[0]
queryMax[0] == wob;
wob;
int
int queryFlags
queryFlags ==
VWQueue.QUERY_MIN_VALUES_INCLUSIVE
VWQueue.QUERY_MIN_VALUES_INCLUSIVE ++
VWQueue.QUERY_MAX_VALUES_INCLUSIVE;
VWQueue.QUERY_MAX_VALUES_INCLUSIVE;
int
int queryType ==
queryType
VWFetchType.FETCH_TYPE_QUEUE_ELEMENT;
VWFetchType.FETCH_TYPE_QUEUE_ELEMENT;
VWQueuequery
VWQueuequery query
query ==
queue.createQuery(queryIndex,queryMin,
queue.createQuery(queryIndex,queryMin,
queryMax,queryFlags,null,null,queryType);
queryMax,queryFlags,null,null,queryType);
VWQueueElementqueueElement
VWQueueElementqueueElement == (VWQueueElement)
(VWQueueElement)
query.next();
query.next();
© Copyright IBM Corporation 2011

Figure 5-32. Sample code to query a queue F1561.0

Notes:
The sample code in this page assumes that a VWSession is already established and
assigned to a variable called myPESession.

5-40 IBM FileNet BPM 5.0: Java API Programming © Copyright IBM Corp. 2011
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
V5.4
Student Notebook

Uempty
Query a queue
Sample code to display queue items

while
while (query.hasNext())
(query.hasNext()) {{
VWQueueElement
VWQueueElement queueElement
queueElement == (VWQueueElement)
(VWQueueElement)
query.next();
query.next();
workFlowName = queueElement.getWorkflowName();
workFlowName = queueElement.getWorkflowName();
subject
subject == queueElement.getFieldValue
queueElement.getFieldValue
("F_Subject").toString();
("F_Subject").toString();
wobNumber = queueElement.getWorkObjectNumber();
wobNumber = queueElement.getWorkObjectNumber();
userID
userID == (Integer)
(Integer) queueElement.getFieldValue
queueElement.getFieldValue
("F_BoundUser");
("F_BoundUser");
userName = myPESession.convertIdToUserName(userID);
userName = myPESession.convertIdToUserName(userID);
System.out.println("WorkFlowName
System.out.println("WorkFlowName == "" ++ workFlowName
workFlowName
++ "Subject=
"Subject= " + subject +"WOB Number= ""
" + subject +"WOB Number=
+wobNumber
+wobNumber ++ "UserName
"UserName == "+
"+ userName);
userName);
}}

© Copyright IBM Corporation 2011

Figure 5-33. Sample code to display queue items F1561.0

Notes:

© Copyright IBM Corp. 2011 Unit 5. Find Work 5-41

Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
Student Notebook

Query a queue
Demonstrations
• Retrieve queues.
• Query a queue using an index.
–Explore the code sample.
–Run the solution code.
–Observe the results.

© Copyright IBM Corporation 2011

Figure 5-34. Demonstrations F1561.0

Notes:
Demonstration notes
1. Start Eclipse and open the BPMJavaAPISolution project.
2. Review the code for retrieving the queues in the getQueuesEDU (…) method in the
FindWorkEDU.java file.
3. Review the different flags used to retrieve different type of queues in the main(…)
method (where the getQueuesEDU (…) method is called).
4. Run the code and verify the results as instructed in the “Find Work” unit in the Student
Exercises.
5. Repeat steps 2 and 4 for querying a queue using an index in the queryQueueEDU (…)
method in the FindWorkEDU.java file.

5-42 IBM FileNet BPM 5.0: Java API Programming © Copyright IBM Corp. 2011
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
V5.4
Student Notebook

Uempty
Query a queue
Activities
In your Student Exercises
• Unit: Find work
• Lesson: Query a queue
• Activities:
– Retrieve queues.
–Query a queue for all elements.
–Query a queue using a filter.
–Query a queue using an index.

© Copyright IBM Corporation 2011

Figure 5-35. Activities F1561.0

Notes:
Use your Student Exercises to perform the activities listed.

© Copyright IBM Corp. 2011 Unit 5. Find Work 5-43

Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
Student Notebook

5-44 IBM FileNet BPM 5.0: Java API Programming © Copyright IBM Corp. 2011
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
V5.4
Student Notebook

Uempty Lesson 5.3. Query an event log

© Copyright IBM Corp. 2011 Unit 5. Find Work 5-45

Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
Student Notebook

Lesson:
Query an event log
• Why is this lesson important to you?
– A customer wants to know the status of his order. The workflow for
this order is completed. You cannot query for the information in either
roster or queue for completed workflows. You are going to write code
to query the event log to track activity based on workflow-related
event for the required information.

© Copyright IBM Corporation 2011

Figure 5-36. Lesson: Query an event log F1561.0

Notes:

5-46 IBM FileNet BPM 5.0: Java API Programming © Copyright IBM Corp. 2011
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
V5.4
Student Notebook

Uempty
Query an event log
Activities that you need to complete

• Query an event log for all elements.

• Query an event log using a filter.

© Copyright IBM Corporation 2011

Figure 5-37. Activities that you need to complete F1561.0

Notes:
These are the activities that you are going to perform in this lesson.

© Copyright IBM Corp. 2011 Unit 5. Find Work 5-47

Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
Student Notebook

Query an event log

Steps to retrieve log elements (1)

1. Retrieve the event log to be searched.

vwSession.fetchEventLog(…)
vwSession.fetchEventLog(…)

2. Set the query parameters.

queryFlags
queryFlags == VWLog.QUERY_NO_OPTIONS
VWLog.QUERY_NO_OPTIONS
queryFilter
queryFilter == "F_EventType
"F_EventType == 140"
140"

3. Perform the query and count the elements returned.

vwLog.startQuery(…)
vwLog.startQuery(…)
vwLogQuery.fetchCount()
vwLogQuery.fetchCount()
vwLogQuery.next()
vwLogQuery.next()

© Copyright IBM Corporation 2011

Figure 5-38. Steps to retrieve log elements (1) F1561.0

Notes:

5-48 IBM FileNet BPM 5.0: Java API Programming © Copyright IBM Corp. 2011
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
V5.4
Student Notebook

Uempty
Query an event log
Steps to retrieve log elements (2)

4. Retrieve information from individual log element.

vwLogElement.getEventType()
vwLogElement.getEventType()
vwLoggingOptionType.getLocalizedString(…)
vwLoggingOptionType.getLocalizedString(…)
vwLogElement.getFieldNames()
vwLogElement.getFieldNames()
vwLogElement.getFieldValue(…)
vwLogElement.getFieldValue(…)

© Copyright IBM Corporation 2011

Figure 5-39. Steps to retrieve log elements (2) F1561.0

Notes:

© Copyright IBM Corp. 2011 Unit 5. Find Work 5-49

Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
Student Notebook

Query an event log

vwSession.fetchEventLog(…)

public
public VWLog
VWLog fetchEventLog(String
fetchEventLog(String
eventLogName)
eventLogName)

• Parameters
–eventLogName - Specify an event log name.
• Returns
–A VWLog object representing the named event log
• Notes
–A list of valid event log names can be retrieved with the
fetchEventLogNames()method.

© Copyright IBM Corporation 2011

Figure 5-40. vwSession.fetchEventLog(...) F1561.0

Notes:

5-50 IBM FileNet BPM 5.0: Java API Programming © Copyright IBM Corp. 2011
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
V5.4
Student Notebook

Uempty
Query an event log
vwLog.startQuery(…)
public
public VWLogQuery
VWLogQuery startQuery
startQuery
(String
(String indexName,Object[] minValues,
indexName,Object[] minValues,
Object[]
Object[] maxValues,int
maxValues,int queryFlags,
queryFlags,
String filter,Object[] substitutionVars)
String filter,Object[] substitutionVars)

• Parameters
–indexName - Specify the name of a user or system-defined database
index key for the log element items, or a system search field name.
• Returns
–A VWLogQuery instance from which the query fetches items
• Notes
–This method fetches log items based on conditions specified in the
parameters.

© Copyright IBM Corporation 2011

Figure 5-41. vwLog.startQuery(...) F1561.0

Notes:
minValues - Specify an array of minimum values used to compare index key fields.
maxValues - Specify an array of maximum values used to compare the index key fields.
queryFlags - Specify a value that identifies the query options.
filter - Specify an SQL WHERE clause to be used as a filter, which has placeholder
variables that are replaced by values in the substitutionVars parameter.
substitutionVars - Specify an array of objects containing the values to substitute for the
placeholder variables specified in the filter parameter.
Valid query options are as follows:
0: QUERY_NO_OPTIONS
32: QUERY_MIN_VALUE_INCLUSIVE
64: QUERY_MAX_VALUE_INCLUSIVE
You can use the + (additive plus) operator to combine these options.

© Copyright IBM Corp. 2011 Unit 5. Find Work 5-51

Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
Student Notebook

Query an event log

vwLogQuery.fetchCount()

public
public int
int fetchCount()
fetchCount()

• Parameters
–None
• Returns
–An integer value indicating the number of records that can be
retrieved in the log, using this logQuery object
• Notes
–Results are approximate because the record set might change
before the query returns.

© Copyright IBM Corporation 2011

Figure 5-42. vwLogQuery.fetchCount() F1561.0

Notes:

5-52 IBM FileNet BPM 5.0: Java API Programming © Copyright IBM Corp. 2011
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
V5.4
Student Notebook

Uempty
Query an event log
vwLogElement.getEventType()

public
public int
int getEventType()
getEventType()

• Parameters
–None
• Returns
–An integer value indicating the event type
• Notes
–This method gets the event type of the log record.
–The event type characterizes events the system logs for various
logging options.
–System events are always logged to the DefaultEventLog.

© Copyright IBM Corporation 2011

Figure 5-43. vwLogElement.getEventType() F1561.0

Notes:
Help path
• IBM FileNet P8 Version 5.0 Information Center > Integrating workflow into document
management > Process applications concepts > Events > Event logging categories
Process Engine events relate to the following categories:
Process Engine (VW)
Work objects (WO)
Work Performers (WP)
Additional methods on this object
The VWLogElement object also has the following method that is used in the activity for this
lesson:
public String[] getFieldNames()

© Copyright IBM Corp. 2011 Unit 5. Find Work 5-53

Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
Student Notebook

Examples of system events

LOGGING_OPTION_TYPE_VW_VWUserLogin (240)
LOGGING_OPTION_TYPE_VW_VWUserLogout (250)
LOGGING_OPTION_TYPE_VW_VWStartTransfer (260)

5-54 IBM FileNet BPM 5.0: Java API Programming © Copyright IBM Corp. 2011
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
V5.4
Student Notebook

Uempty
Query an event log
vwLogElement.getFieldValue(…)
public
public Object
Object getFieldValue(String
getFieldValue(String fieldName)
fieldName)

• Parameters
–fieldName - Specify the name of the field from which to return the
value.
• Returns
–The value of the named, user-defined field

© Copyright IBM Corporation 2011

Figure 5-44. vwLogElement.getFieldValue(...) F1561.0

Notes:

© Copyright IBM Corp. 2011 Unit 5. Find Work 5-55

Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
Student Notebook

Query an event log

vwLoggingOptionType.getLocalizedString(…)

public
public static
static String
String getLocalizedString
getLocalizedString
(int
(int loggingEventType)
loggingEventType)

• Parameters
–loggingEventType - Specify an integer value for the logging event
type.
• Returns
–The localized string representation of the logging event type
• Notes
–If the specified loggingEventType parameter is not a recognized
logging event value, the method returns an UnknownEvent message
string.

© Copyright IBM Corporation 2011

Figure 5-45. vwLoggingOptionType.getLocalizedString(...) F1561.0

Notes:
See the Process Engine Java API Developer Help Java Docs information on the
VWLogElement.getEventType() method for a list of valid logging event types.

5-56 IBM FileNet BPM 5.0: Java API Programming © Copyright IBM Corp. 2011
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
V5.4
Student Notebook

Uempty
Query an event log
Sample code to query the event log

VWLog
VWLog log
log ==
mySession.fetchEventLog(“LoanLog");
mySession.fetchEventLog(“LoanLog");
queryFilter
queryFilter == "F_EventType
"F_EventType == 140";
140";
queryFlags
queryFlags == VWLog.QUERY_NO_OPTIONS;
VWLog.QUERY_NO_OPTIONS;
VWLogQuery
VWLogQuery query
query ==
log.startQuery(null,null,null,
log.startQuery(null,null,null,
queryFlags,queryFilter,null);
queryFlags,queryFilter,null);
VWLogElement
VWLogElement logElement
logElement == (VWLogElement)
(VWLogElement)
query.next();
query.next();

© Copyright IBM Corporation 2011

Figure 5-46. Sample code to query the event log F1561.0

Notes:
Due to space limitations on the page, the following declarations do not appear in the
sample code:
String queryFilter;
int queryFlags;
int EventType;
String EventNumber;

© Copyright IBM Corp. 2011 Unit 5. Find Work 5-57

Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
Student Notebook

Query an event log

Sample code to retrieve event log elements

int
int eventType
eventType == logElement.getEventType();
logElement.getEventType();
String
String eventNumber
eventNumber ==
VWLoggingOptionType.getLocalizedString
VWLoggingOptionType.getLocalizedString
(logElement.getEventType());
(logElement.getEventType());
String[]
String[] fieldNames
fieldNames ==
logElement.getFieldNames();
logElement.getFieldNames();
for(int
for(int i=0;i<fieldNames.length;i++){
i=0;i<fieldNames.length;i++){
fieldName
fieldName == fieldNames[i];
fieldNames[i];
String
String fieldValue=logElement.getFieldValue
fieldValue=logElement.getFieldValue
(fieldNames[0]).toString();
(fieldNames[0]).toString();
}}

© Copyright IBM Corporation 2011

Figure 5-47. Sample code to retrieve event log elements F1561.0

Notes:

5-58 IBM FileNet BPM 5.0: Java API Programming © Copyright IBM Corp. 2011
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
V5.4
Student Notebook

Uempty
Query an event log
Demonstrations
• Query an event log using a filter.
–Explore the code sample.
–Run the solution code.
–Observe the results.

© Copyright IBM Corporation 2011

Figure 5-48. Demonstrations F1561.0

Notes:
Demonstration notes
1. Start Eclipse and open the BPMJavaAPISolution project.
2. Review the code for querying an event log using the filter in the queryLogEDU (…)
method in the FindWorkEDU.java file.
3. Run the code and verify the results as instructed in the “Find Work” unit in the Student
Exercises.

© Copyright IBM Corp. 2011 Unit 5. Find Work 5-59

Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
Student Notebook

Query an event log

Activities
In your Student Exercises
• Unit: Find work
• Lesson: Query an event log
• Activities:
– Query an event log for all elements.
– Query an event log using a filter.

© Copyright IBM Corporation 2011

Figure 5-49. Activities F1561.0

Notes:
Use your Student Exercises to perform the activities listed.

5-60 IBM FileNet BPM 5.0: Java API Programming © Copyright IBM Corp. 2011
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
V5.4
Student Notebook

Uempty Unit 6. Process Work

What this unit is about

This unit describes how to write code using Process Engine Java API
to do the following:
Retrieve the step element from the queue
Retrieve the parameter values from a step element
Set the parameter values for a step element
Send the work item on to its next destination in the workflow

What you should be able to do

After completing this unit, you should be able to:
• Retrieve a step elements from the Inbox.
• Retrieve parameters values for a step element.
• Set parameters values for a step element.
• Get processing options of a step element.
• Complete the work item.

How you will check your progress

• Successfully complete the activities in the Student Exercises book.

References
www.ibm.com/support/documentation/us/en (Support & downloads
page)
Note: IBM FileNet products belong to the Information Management
product set.

© Copyright IBM Corp. 2011 Unit 6. Process Work 6-1

Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
Student Notebook

Process Work
Unit lessons
This unit contains the following lessons:
• Retrieve a step element
• Retrieve parameter values for a step element
• Set parameter values for a step element
• Complete a work item

© Copyright IBM Corporation 2011

Figure 6-1. Unit lessons F1561.0

Notes:
Lessons in this unit
This unit has four lessons. After the first lesson, each lesson relies on information and skills
taught in the prior lessons. For best results, do these lessons in the sequence presented.
Retrieve a step element – In this lesson, you write code to retrieve the step element from
the queue.
Retrieve parameter values for a step element – In this lesson, you write code to retrieve
the parameter values from a step element.
Set parameter values for a step element – In this lesson, you write code to set parameter
values for a step element.
Complete a work item - In this lesson, you write code to send the work item on to its next
destination in the workflow.

6-2 IBM FileNet BPM 5.0: Java API Programming © Copyright IBM Corp. 2011
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
V5.4
Student Notebook

Uempty Lesson 6.1. Retrieve a step element

© Copyright IBM Corp. 2011 Unit 6. Process Work 6-3

Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
Student Notebook

Lesson:
Retrieve a step element
• Why is this lesson important to you?
– In order to process a work item in step processor application, the
appropriate step element must be retrieved from the queue. You are
going to write code to retrieve the step element from the queue.

© Copyright IBM Corporation 2011

Figure 6-2. Lesson: Retrieve a step element F1561.0

Notes:

6-4 IBM FileNet BPM 5.0: Java API Programming © Copyright IBM Corp. 2011
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
V5.4
Student Notebook

Uempty
Retrieve a step element
Activities that you need to complete

• Retrieve a step element from the Inbox.

© Copyright IBM Corporation 2011

Figure 6-3. Activities that you need to complete F1561.0

Notes:
These are the activities that you are going to perform in this lesson.

© Copyright IBM Corp. 2011 Unit 6. Process Work 6-5

Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
Student Notebook

Retrieve a step element

Steps to retrieve step element

1. Get the queue containing the work item

2. Set the query parameters to get step elements.

queryFlags
queryFlags == ...
...
fetchType
fetchType == ...
...

3. Perform the queue query.

4. Get the desired step element from the queue.

© Copyright IBM Corporation 2011

Figure 6-4. Steps to retrieve step element F1561.0

Notes:
Help paths
• IBM FileNet P8 Version 5.0 Information Center > Developing IBM FileNet P8
applications > Process Engine Development > Process Java Developer's Guide >
Developing Process Applications > Developing Step Processors > Fundamental Step
Processor Operations > Querying for Step Elements or Work Objects
• IBM FileNet P8 Version 5.0 Information Center > Developing IBM FileNet P8
applications > Process Engine Development > Process Java Developer's Guide >
Developing Process Applications > Developing User Inboxes: an Overview >
Fundamental User Inbox Operations > Opening a Work Item

6-6 IBM FileNet BPM 5.0: Java API Programming © Copyright IBM Corp. 2011
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
V5.4
Student Notebook

Uempty
Retrieve a step element
Inbox and Inbox(0)
• Inbox
–Represents the Inbox of specified user.
–When you retrieve step elements from an Inbox queue, it
returns the work item assigned to the specific user.
• Inbox(0)
–Represents the Inbox of all the users.
–When you retrieve step elements from an Inbox(0) queue, it
returns the work items assigned to all users in that region.

© Copyright IBM Corporation 2011

Figure 6-5. Inbox and Inbox(0) F1561.0

Notes:

© Copyright IBM Corp. 2011 Unit 6. Process Work 6-7

Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
Student Notebook

Retrieve a step element

vwQueue.createQuery(…)

public
public VWQueueQuery
VWQueueQuery createQuery
createQuery
(String
(String indexName,
indexName, Object[]
Object[] minValues,
minValues,
Object[] maxValues, int queryFlags,
Object[] maxValues, int queryFlags,
String
String filter,
filter, Object[]
Object[] substitutionVars,
substitutionVars,
int
int fetchType)
fetchType)
• Parameters
–Covered in a previous unit
• Returns
–A VWQueueQuery object for the queue from which items are fetched
with the VWQueueQuery.next() method
• Notes:
–To return step elements, use
VWFetchType.FETCH_TYPE_STEP_ELEMENT
–Users can fetch their own step elements, regardless of their queue
access privilege.
© Copyright IBM Corporation 2011

Figure 6-6. vwQueue.createQuery(...) F1561.0

Notes:
The VWQueueQuery.next() method is used in a manner similar to the use of the next()
method of the Iterator interface in Java 2.
Query flags use lock Object and set buffer size

6-8 IBM FileNet BPM 5.0: Java API Programming © Copyright IBM Corp. 2011
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
V5.4
Student Notebook

Uempty
Retrieve a step element
Sample code to retrieve a step element

• Retrieve all step elements from Inbox.

VWQueue
VWQueue queue
queue == myPESession.getQueue("Inbox");
myPESession.getQueue("Inbox");
int
int queryFlag
queryFlag == VWQueue.QUERY_READ_BOUND;
VWQueue.QUERY_READ_BOUND;
int
int queryType
queryType ==
VWFetchType.FETCH_TYPE_STEP_ELEMENT;
VWFetchType.FETCH_TYPE_STEP_ELEMENT;
VWQueueQuery
VWQueueQuery query
query == queue.createQuery
queue.createQuery (null,
(null,
null,null,
null,null, queryFlag,null,null,queryType);
queryFlag,null,null,queryType);

• Get an individual step element.

VWStepElement
VWStepElement stepElement
stepElement == (VWStepElement)
(VWStepElement)
query.next();
query.next();
String
String stepName
stepName == stepElement.getStepName();
stepElement.getStepName();
System.out.println("Step
System.out.println("Step element
element name:
name: "" ++
stepName);
stepName);
© Copyright IBM Corporation 2011

Figure 6-7. Sample code to retrieve a step element F1561.0

Notes:
The sample code above assumes a valid VWSession object has been returned and
assigned to this myPESession variable.
QUERY_READ_BOUND
Value of 2. Include this value in the queryFlags parameter of the createQuery() method to
return work items that are bound to a user or machine.

© Copyright IBM Corp. 2011 Unit 6. Process Work 6-9

Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
Student Notebook

Retrieve a step element

Demonstrations
• Retrieve a step element from the Inbox.
–Explore the code sample.
–Run the solution code.
–Observe the results.

© Copyright IBM Corporation 2011

Figure 6-8. Demonstrations F1561.0

Notes:
Demonstration notes
1. Start Eclipse and open the BPMJavaAPISolution project.
2. Review the code for the processWorkEDU (…) method in the ProcessWorkEDU.java file.
Note: The code for this task ends just before the method call getParametersEDU(…).
3. Run the code and verify the results as instructed in the “Process Work” unit in the
Student Exercises.

6-10 IBM FileNet BPM 5.0: Java API Programming © Copyright IBM Corp. 2011
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
V5.4
Student Notebook

Uempty
Retrieve a step element
Activities
In your Student Exercises
• Unit: Process work
• Lesson: Retrieve a step element
• Activities:
–Retrieve a step element from the Inbox.

© Copyright IBM Corporation 2011

Figure 6-9. Activities F1561.0

Notes:
Use your Student Exercises to perform the activities listed.

© Copyright IBM Corp. 2011 Unit 6. Process Work 6-11

Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
Student Notebook

6-12 IBM FileNet BPM 5.0: Java API Programming © Copyright IBM Corp. 2011
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
V5.4
Student Notebook

Uempty Lesson 6.2. Retrieve parameter values for a step element

© Copyright IBM Corp. 2011 Unit 6. Process Work 6-13

Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
Student Notebook

Lesson:
Retrieve parameter values for a step element
• Why is this lesson important to you?
– In order to process a work item in the step processor application,
current information included in the step element must be retrieved so
that it can be displayed to the user. You are going to write code to get
the parameter values from a step element.

© Copyright IBM Corporation 2011

Figure 6-10. Lesson: Retrieve parameter values for a step element F1561.0

Notes:
This lesson describes how to retrieve parameter values for a step element and is very
similar to the lesson of the same name in the “Create Work” unit of this course.

6-14 IBM FileNet BPM 5.0: Java API Programming © Copyright IBM Corp. 2011
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
V5.4
Student Notebook

Uempty
Retrieve parameter values for a step element
Activities that you need to complete

• Retrieve parameters values for a step.

© Copyright IBM Corporation 2011

Figure 6-11. Activities that you need to complete F1561.0

Notes:
These are the activities that you are going to perform in this lesson.

© Copyright IBM Corp. 2011 Unit 6. Process Work 6-15

Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
Student Notebook

Retrieve parameter values for a step element

Steps to retrieve queue elements

1. Retrieve the user- and system-defined parameters.

vwStepElement.getParameters(…)
vwStepElement.getParameters(…)

2. Get the name, data type, read and write mode, and value for
each parameter.

vwParameter.getName()
vwParameter.getName()
VWFieldType.getLocalizedString(…)
VWFieldType.getLocalizedString(…)
VWModeType.getLocalizedString(…)
VWModeType.getLocalizedString(…)
vwParameter.getStringValue()
vwParameter.getStringValue()

© Copyright IBM Corporation 2011

Figure 6-12. Steps to retrieve queue elements F1561.0

Notes:

6-16 IBM FileNet BPM 5.0: Java API Programming © Copyright IBM Corp. 2011
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
V5.4
Student Notebook

Uempty
Retrieve parameter values for a step element
vwStepElement.getParameters(...)

public
public VWParameter[]
VWParameter[] getParameters
getParameters
(int
(int fieldTypeFlag,int
fieldTypeFlag,int fieldCreatorFlag)
fieldCreatorFlag)
• Parameters
–fieldTypeFlag – Specify the parameter type or types.
–fieldCreatorFlag – Specify the field creator type (user, system, or
both).
• Returns
–An array of VWParameter objects: the system- or user-defined
parameters in this step as specified in the fieldCreatorFlag variable
–Null if no parameters exist or the system cannot find parameters.

© Copyright IBM Corporation 2011

Figure 6-13. vwStepElement.getParameters(...) F1561.0

Notes:
For the fieldTypeFlag parameter of this method, the following integer values (given in
parentheses) are valid.
Integer (FIELD_TYPE_INT)
String (FIELD_TYPE_STRING)
Boolean (FIELD_TYPE_BOOLEAN)
Float (FIELD_TYPE_FLOAT)
Time (FIELD_TYPE_TIME)
Attachment (FIELD_TYPE_ATTACHMENT)
Participant (FIELD_TYPE_PARTICIPANT)
All types (ALL_FIELD_TYPES)
You can combine the flag types.

© Copyright IBM Corp. 2011 Unit 6. Process Work 6-17

Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
Student Notebook

For the fieldCreatorFlag parameter of this method, the following integer values (given in
parentheses) are valid.
User (FIELD_USER_DEFINED)
System (FIELD_SYSTEM_DEFINED)
User and System (FIELD_USER_AND_SYSTEM_DEFINED)

6-18 IBM FileNet BPM 5.0: Java API Programming © Copyright IBM Corp. 2011
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
V5.4
Student Notebook

Uempty
Retrieve parameter values for a step element
vwStepElement.getStepName()

public
public String
String getStepName()
getStepName()

• Parameters
–None
• Returns
–A String containing the step name
–Null if the field does not exist.
• Notes
–This method overrides getStepName in the VWFieldsObject class.

© Copyright IBM Corporation 2011

Figure 6-14. vwStepElement.getStepName() F1561.0

Notes:
Additional methods on this object
The VWStepElement object also has the following method that is used in this lesson’s lab
exercise:
public String getStepDescription()
This method returns the description of the current step.

© Copyright IBM Corp. 2011 Unit 6. Process Work 6-19

Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
Student Notebook

Retrieve parameter values for a step element

vwParameter.getMode()

public
public int
int getMode()
getMode()

• Parameters
–None
• Returns
–An integer value that indicates the mode of the step parameter
• Notes
–Valid modes returned are as follows:
• MODE_TYPE_IN (1) if the VWParameter is read-only
• MODE_TYPE_OUT (2) if the VWParameter is write-only
• MODE_TYPE_IN_OUT (3) if the VWParameter is read and write

© Copyright IBM Corporation 2011

Figure 6-15. vwParameter.getMode() F1561.0

Notes:
Additional methods on this object:
The following methods of the VWParameter object are also used in the lab exercises of this
lesson:
public String getName()
This method returns the VWParameter name.
public Object getValue()
This method returns the value of the parameter in a VWFieldType object. If the field type of
the parameter is an array, the returned object must be cast to the appropriate array type.
public String getStringValue()
This method returns the value of this VWParameter in a String.
public int getFieldType()
This method returns an integer value associated with the field type of the parameter.

6-20 IBM FileNet BPM 5.0: Java API Programming © Copyright IBM Corp. 2011
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
V5.4
Student Notebook

Uempty
Retrieve parameter values for a step element
VWFieldType.getLocalizedString(...)

public
public static
static String
String getLocalizedString
getLocalizedString
(int
(int theFieldType)
theFieldType)

• Parameters
–theFieldType – Specify an integer value associated with the field
type.
• Returns
–A String containing the localized data field type

© Copyright IBM Corporation 2011

Figure 6-16. VWFieldType.getLocalizedString(...) F1561.0

Notes:
For the theFieldType parameter of this method, the following integer values (given in
parentheses) are valid.
Attachment (FIELD_TYPE_ATTACHMENT)
Boolean (FIELD_TYPE_BOOLEAN)
Float (FIELD_TYPE_FLOAT)
Integer (FIELD_TYPE_INT)
Participant (FIELD_TYPE_PARTICIPANT)
String (FIELD_TYPE_STRING)
Time (FIELD_TYPE_TIME)
XML (FIELD_TYPE_XML)

© Copyright IBM Corp. 2011 Unit 6. Process Work 6-21

Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
Student Notebook

Retrieve parameter values for a step element

VWModeType.getLocalizedString()

public
public static
static String
String getLocalizedString
getLocalizedString
(int
(int theModeType)
theModeType)

• Parameters
–theModeType – Specify an integer value associated with the mode
type.
• Returns
–The localized string representation of the mode type

© Copyright IBM Corporation 2011

Figure 6-17. VWModeType.getLocalizedString() F1561.0

Notes:
For the theModeType parameter of this method, the following integer values are valid.
MODE_TYPE_IN
Indicates that the argument is an input parameter, which is passed by value.
MODE_TYPE_IN_OUT
Indicates that the argument is an input/output parameter, which is passed by
reference.
MODE_TYPE_OUT
Indicates that the argument is an output parameter, which is passed by reference.

6-22 IBM FileNet BPM 5.0: Java API Programming © Copyright IBM Corp. 2011
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
V5.4
Student Notebook

Uempty
Retrieve parameter values for a step element
vwStepElement.getStepResponses()
public
public String[]
String[] getStepResponses()
getStepResponses()

• Parameters
–None
• Returns
–The available responses for the current step in String array
–Null if no responses exist

© Copyright IBM Corporation 2011

Figure 6-18. vwStepElement.getStepResponses() F1561.0

Notes:

© Copyright IBM Corp. 2011 Unit 6. Process Work 6-23

Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
Student Notebook

Retrieve parameter values for a step element

Sample code to retrieve parameter values

• Retrieve the user- and system-defined parameters.

VWStepElement
VWStepElement stepElement;
stepElement;
VWParameter[]
VWParameter[] parameters
parameters == stepElement.
stepElement.
getParameters(VWFieldType.ALL_FIELD_TYPES,
getParameters(VWFieldType.ALL_FIELD_TYPES,
VWStepElement.FIELD_USER_AND_SYSTEM_DEFINED);
VWStepElement.FIELD_USER_AND_SYSTEM_DEFINED);

• Get name, data type, read/write mode, value for each

parameter.
parameterName
parameterName == parameters[i].getName();
parameters[i].getName();
parameterType
parameterType == VWFieldType.getLocalizedString
VWFieldType.getLocalizedString
(parameters[i].getFieldType());
(parameters[i].getFieldType());
parameterMode
parameterMode = VWModeType.getLocalizedString
= VWModeType.getLocalizedString
(parameters[i].getMode());
(parameters[i].getMode());
parameterValue =parameters[i].getStringValue();
parameterValue =parameters[i].getStringValue();

© Copyright IBM Corporation 2011

Figure 6-19. Sample code to retrieve parameter values F1561.0

Notes:

6-24 IBM FileNet BPM 5.0: Java API Programming © Copyright IBM Corp. 2011
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
V5.4
Student Notebook

Uempty
Retrieve parameter values for a step element
Sample code to retrieve step element responses
• Retrieve the VW step element responses.
String[]
String[] myResponses
myResponses ==
stepElement.getStepResponses();
stepElement.getStepResponses();
if(myResponses
if(myResponses !=
!= null){
null){
int
int len
len == myResponses.length;
myResponses.length;
for(int
for(int jj == 0;
0; jj << len;
len; j++
j++ ))
System.out.println(myResponses[j]);
System.out.println(myResponses[j]);
}}

© Copyright IBM Corporation 2011

Figure 6-20. Sample code to retrieve step element responses F1561.0

Notes:

© Copyright IBM Corp. 2011 Unit 6. Process Work 6-25

Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
Student Notebook

Retrieve parameter values for a step element

Activities
In your Student Exercises
• Unit: Process work
• Lesson: Retrieve parameter values for a step element
• Activities:
– Retrieve parameters values for a step.

© Copyright IBM Corporation 2011

Figure 6-21. Activities F1561.0

Notes:
Use your Student Exercises to perform the activities listed.

6-26 IBM FileNet BPM 5.0: Java API Programming © Copyright IBM Corp. 2011
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
V5.4
Student Notebook

Uempty Lesson 6.3. Set parameter values for a step element

© Copyright IBM Corp. 2011 Unit 6. Process Work 6-27

Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
Student Notebook

Lesson:
Set parameter values for a step element
• Why is this lesson important to you?
– Customer order workflows contain customer data for processing. As
the programmer, you are going to write code to Set parameter values
for a step element with customer data.

© Copyright IBM Corporation 2011

Figure 6-22. Lesson: Set parameter values for a step element F1561.0

Notes:
This lesson describes how to set parameter values for a step element and is similar to the
lesson of the same name in the “Create Work” unit of this course.

6-28 IBM FileNet BPM 5.0: Java API Programming © Copyright IBM Corp. 2011
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
V5.4
Student Notebook

Uempty
Set parameter values for a step element
Activities that you need to complete

• Set parameter values for a step element.

© Copyright IBM Corporation 2011

Figure 6-23. Activities that you need to complete F1561.0

Notes:
These are the activities that you are going to perform in this lesson.

© Copyright IBM Corp. 2011 Unit 6. Process Work 6-29

Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
Student Notebook

Set parameter values for a step element

Steps to retrieve queue elements (1)

1. Lock the step element.

vwStepElement.doLock(…)
vwStepElement.doLock(…)

2. Check whether the parameter is read only.

vwParameter.getMode()==VWModeType.MODE_TYPE_IN
vwParameter.getMode()==VWModeType.MODE_TYPE_IN

3. If the parameter is editable, switch through each data type.

switch(VWParameter.getFieldType())
switch(VWParameter.getFieldType())

© Copyright IBM Corporation 2011

Figure 6-24. Steps to retrieve queue elements (1) F1561.0

Notes:

6-30 IBM FileNet BPM 5.0: Java API Programming © Copyright IBM Corp. 2011
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
V5.4
Student Notebook

Uempty
Set parameter values for a step element
Steps to retrieve queue elements (2)

4. For each data type, check a single value or an array.

case
case VWFieldType.FIELD_TYPE_STRING
VWFieldType.FIELD_TYPE_STRING
if
if vwParameter.isArray()
vwParameter.isArray()
5. Set the value for the parameter.
vwStepElement.setParameterValue(…)
vwStepElement.setParameterValue(…)
6. Set the value for the system-defined Response parameter.

vwStepElement.setSelectedResponse(…)
vwStepElement.setSelectedResponse(…)

© Copyright IBM Corporation 2011

Figure 6-25. Steps to retrieve queue elements (2) F1561.0

Notes:

© Copyright IBM Corp. 2011 Unit 6. Process Work 6-31

Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
Student Notebook

Set parameter values for a step element

Steps to set VWParticipant

1. Instantiate a new VWParticipant array.

case
case VWFieldType.FIELD_TYPE_PARTICIPANT
VWFieldType.FIELD_TYPE_PARTICIPANT::
VWParticipant [] tempPart
VWParticipant[] tempPart == new
new
VWParticipant[1];
VWParticipant[1];

2. Set the participant name.

vwParticipant[0 ].setParticipantName(…)
vwParticipant[0]. setParticipantName(…)

3. Set the parameter value.

vwStepElement.setParameterValue(…)
vwStepElement.setParameterValue(…)

© Copyright IBM Corporation 2011

Figure 6-26. Steps to set VWParticipant F1561.0

Notes:

6-32 IBM FileNet BPM 5.0: Java API Programming © Copyright IBM Corp. 2011
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
V5.4
Student Notebook

Uempty
Set parameter values for a step element
Steps to set VWAttachment (1)

1. Get the value for the VWAttachment.

case
case VWFieldType.FIELD_TYPE_ATTACHMENT:
VWFieldType.FIELD_TYPE_ATTACHMENT:
(VWAttachment)parameters[i].getValue()
(VWAttachment)parameters[i].getValue()
2. Set the attachment name.
vwAttachment.setAttachmentName(…)
vwAttachment.setAttachmentName(…)

3. Set the attachment description.

vwAttachment.setAttachmentDescription(…)
vwAttachment.setAttachmentDescription(…)

© Copyright IBM Corporation 2011

Figure 6-27. Steps to set VWAttachment (1) F1561.0

Notes:

© Copyright IBM Corp. 2011 Unit 6. Process Work 6-33

Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
Student Notebook

Set parameter values for a step element

Steps to set VWAttachment (2)

4. Set the type of object.

vwAttachment.setType(…)
vwAttachment.setType(…)

5. Set the library type and name.

vwAttachment.setLibraryType(…)
vwAttachment.setLibraryType(…)
vwAttachment.setLibraryName(…)
vwAttachment.setLibraryName(…)

6. Set the document ID and version.

vwAttachment.setId(…)
vwAttachment.setId(…)
vwAttachment.setVersion(…)
vwAttachment.setVersion(…)
7. Set the parameter value.
vwStepElement.setParameterValue(…)
vwStepElement.setParameterValue(…)
© Copyright IBM Corporation 2011

Figure 6-28. Steps to set VWAttachment (2) F1561.0

Notes:

6-34 IBM FileNet BPM 5.0: Java API Programming © Copyright IBM Corp. 2011
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
V5.4
Student Notebook

Uempty
Set parameter values for a step element
vwStepElement.doLock(…)

public
public void
void doLock(boolean
doLock(boolean overrideLock)
overrideLock)

• Parameters
–overrideLock – Specify whether or not to override the lock.
• Returns
–Nothing
• Notes
–Administrators can take control of the lock on a locked object.
–This method cannot override a system lock.

© Copyright IBM Corporation 2011

Figure 6-29. vwStepElement.doLock(...) F1561.0

Notes:

© Copyright IBM Corp. 2011 Unit 6. Process Work 6-35

Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
Student Notebook

Set parameter values for a step element

vwParameter.isArray()

public
public boolean
boolean isArray()
isArray()

• Returns
–A boolean value:
• True if the parameter is an array
• Otherwise, false

© Copyright IBM Corporation 2011

Figure 6-30. vwParameter.isArray() F1561.0

Notes:

6-36 IBM FileNet BPM 5.0: Java API Programming © Copyright IBM Corp. 2011
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
V5.4
Student Notebook

Uempty
Set parameter values for a step element
vwStepElement.setParameterValue(...)
public
public void
void setParameterValue
setParameterValue
(String
(String parameterName,
parameterName,
Object
Object parameterValue,boolean compareValue)
parameterValue,boolean compareValue)

• Parameters
–parameterName – Specify the name of the parameter for which the
value is to be set.
–parameterValue – Specify the object containing the value being set
in the specified parameter.
–compareValue – Specify a boolean value:
• True to set only the changed values
• False to set all values

© Copyright IBM Corporation 2011

Figure 6-31. vwStepElement.setParameterValue(...) F1561.0

Notes:
This method sets a value for a specified parameter.
• Parameters with VWModeType.MODE_TYPE_IN are read only.
• You can modify only those parameters with the following modes:
VWModeType.MODE_TYPE_OUT
VWModeType.MODE_TYPE_IN_OUT

© Copyright IBM Corp. 2011 Unit 6. Process Work 6-37

Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
Student Notebook

Set parameter values for a step element

vwParticipant.setParticipantName(...)
Public
Public void
void setParticipantName
setParticipantName
(String
(String theParticipantName)
theParticipantName)

• Parameters
–theParticipantName – Specify the “short” or “login” name of a
participant user or group.

© Copyright IBM Corporation 2011

Figure 6-32. vwParticipant.setParticipantName(...) F1561.0

Notes:

6-38 IBM FileNet BPM 5.0: Java API Programming © Copyright IBM Corp. 2011
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
V5.4
Student Notebook

Uempty
Set parameter values for a step element
vwAttachment.setType(...)
public
public void
void setType(int
setType(int theAttachmentType)
theAttachmentType)

• Parameters
–theAttachmentType – Specify the type of the associated attachment
as an integer.
• Notes
–Examples of types and the values for the constants:
• ATTACHMENT_TYPE_CUSTOM_OBJECT(6)
• ATTACHMENT_TYPE_DOCUMENT (3)
• ATTACHMENT_TYPE_FOLDER (2)
• ATTACHMENT_TYPE_LIBRARY (1)
• ATTACHMENT_TYPE_UNDEFINED (0)
• ATTACHMENT_TYPE_URL (5)

© Copyright IBM Corporation 2011

Figure 6-33. vwAttachment.setType(...) F1561.0

Notes:
The VWAttachment object also has the following methods:
public void setAttachmentName(String theAttachmentName)
Pass a String containing the attachment name as the parameter.
public void setAttachmentDescription(String theAttachmentDescription)
Pass a String containing the attachment description as the parameter.
public void setLibraryType(int theLibraryType)
Pass an integer value for the library or object store type of the attachment as the
parameter.
public void setLibraryName(String theLibraryName)
Pass a String containing the library or object store name as the parameter.
public void setId(String theId)
Pass a String containing the version series GUID as the parameter.

© Copyright IBM Corp. 2011 Unit 6. Process Work 6-39

Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
Student Notebook

public void setVersion(String theVersion)

- Specify the value for the version for the attachment in a String.
- -1 sets the most current released version.
- Empty string sets the most current version.

6-40 IBM FileNet BPM 5.0: Java API Programming © Copyright IBM Corp. 2011
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
V5.4
Student Notebook

Uempty
Set parameter values for a step element
vwStepElement.setSelectedResponse(...)
public
public void
void setSelectedResponse
setSelectedResponse
(String
(String response)
response)
• Parameters
–response – Specify the response that is selected for this step.

© Copyright IBM Corporation 2011

Figure 6-34. vwStepElement.setSelectedResponse(...) F1561.0

Notes:

© Copyright IBM Corp. 2011 Unit 6. Process Work 6-41

Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
Student Notebook

Set parameter values for a step element

Sample code to set parameters values

stepElement.doLock(true);
stepElement.doLock(true);
if(parameters[i].getMode()==
if(parameters[i].getMode()==
VWModeType.MODE_TYPE_IN)
VWModeType.MODE_TYPE_IN) {{
System.out.println("Read
System.out.println("Read Only.");
Only.");
}}
switch(parameters[i].getFieldType())
switch(parameters[i].getFieldType())
case
case VWFieldType.FIELD_TYPE_STRING:
VWFieldType.FIELD_TYPE_STRING:
if
if (parameters[i].isArray())
(parameters[i].isArray()) {{
stepElement.setParameterValue
stepElement.setParameterValue
(parameterName,value,true);
(parameterName,value,true);
}}
...
...

© Copyright IBM Corporation 2011

Figure 6-35. Sample code to set parameters values F1561.0

Notes:

6-42 IBM FileNet BPM 5.0: Java API Programming © Copyright IBM Corp. 2011
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
V5.4
Student Notebook

Uempty
Set parameter values for a step element
Sample code to set VWParticipant

case
case VWFieldType.FIELD_TYPE_PARTICIPANT:
VWFieldType.FIELD_TYPE_PARTICIPANT:
...
...
VWParticipant[]
VWParticipant[] tempPart
tempPart == new
new
VWParticipant[1];
VWParticipant[1];
...
...
String
String tempStr
tempStr == “Administrator”;
“Administrator”;
tempPart[0].setParticipantName(tempStr);
tempPart[0].setParticipantName(tempStr);
stepElement.setParameterValue
stepElement.setParameterValue
(parameterName,tempPart,true);
(parameterName,tempPart,true);
...
...

© Copyright IBM Corporation 2011

Figure 6-36. Sample code to set VWParticipant F1561.0

Notes:
This example shows setting a single value for VWParticipant. To specify multiple
participants, the VWParticipant array (tempPart) would need to be declared appropriately,
and each element of the array would be set to its value using a separate call to the
setParticipantName method. For example:

tempPart[1].setParticipantName(participantTwo);
tempPart[2].setParticipantName(participantThree);

© Copyright IBM Corp. 2011 Unit 6. Process Work 6-43

Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
Student Notebook

Set parameter values for a step element

Sample code to set VWAttachment
case
case VWFieldType.FIELD_TYPE_ATTACHMENT:
VWFieldType.FIELD_TYPE_ATTACHMENT:
VWAttachment
VWAttachment tempAtt
tempAtt == (VWAttachment)
(VWAttachment)
parameters[i].getValue();
parameters[i].getValue();
tempAtt.setAttachmentName("NewDocument");
tempAtt.setAttachmentName("NewDocument");
tempAtt.setAttachmentDescription("A
tempAtt.setAttachmentDescription("A document
document added
added
programmatically");
programmatically");
tempAtt.setType(VWAttachmentType.
tempAtt.setType(VWAttachmentType.
ATTACHMENT_TYPE_DOCUMENT);
ATTACHMENT_TYPE_DOCUMENT);
tempAtt.setLibraryType(VWLibraryType.
tempAtt.setLibraryType(VWLibraryType.
LIBRARY_TYPE_CONTENT_ENGINE);
LIBRARY_TYPE_CONTENT_ENGINE);
tempAtt.setLibraryName(“Loan");
tempAtt.setLibraryName(“Loan");
tempAtt.setId("{BBE5AD7F-2449-4DC3-AA38-
tempAtt.setId("{BBE5AD7F-2449-4DC3-AA38-
012A65EC4286}");
012A65EC4286}");
tempAtt.setVersion("-1");
tempAtt.setVersion("-1");
stepElement.setParameterValue(parameterName,
stepElement.setParameterValue(parameterName,
tempAtt,true);
tempAtt,true);

© Copyright IBM Corporation 2011

Figure 6-37. Sample code to set VWAttachment F1561.0

Notes:

6-44 IBM FileNet BPM 5.0: Java API Programming © Copyright IBM Corp. 2011
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
V5.4
Student Notebook

Uempty
Set parameter values for a step element
Sample code to set response parameter value

• Set the value for the system-defined Response parameter.

stepElement.setSelectedResponse(responseValue)
stepElement.setSelectedResponse(responseValue)

© Copyright IBM Corporation 2011

Figure 6-38. Sample code to set response parameter value F1561.0

Notes:

© Copyright IBM Corp. 2011 Unit 6. Process Work 6-45

Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
Student Notebook

Set parameter values for a step element

Activities
In your Student Exercises
• Unit: Process work
• Lesson: Set parameter values for a step element
• Activities:
– Set parameter values for a step element.

© Copyright IBM Corporation 2011

Figure 6-39. Activities F1561.0

Notes:
Use your Student Exercises to perform the activities listed.

6-46 IBM FileNet BPM 5.0: Java API Programming © Copyright IBM Corp. 2011
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
V5.4
Student Notebook

Uempty Lesson 6.4. Complete a work item

© Copyright IBM Corp. 2011 Unit 6. Process Work 6-47

Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
Student Notebook

Lesson:
Complete a work item
• Why is this lesson important to you?
– In the step processor application, users must be able to save or
cancel changes made to a work item, and to be able to send the work
item on to its next destination in the workflow. You are going to write
code to handle this final phase of processing in the step processor
application.

© Copyright IBM Corporation 2011

Figure 6-40. Lesson: Complete a work item F1561.0

Notes:

6-48 IBM FileNet BPM 5.0: Java API Programming © Copyright IBM Corp. 2011
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
V5.4
Student Notebook

Uempty
Complete a work item
Activities that you need to complete

• Get processing options of a step element.

• Complete the work item.

© Copyright IBM Corporation 2011

Figure 6-41. Activities that you need to complete F1561.0

Notes:
These are the activities that you are going to perform in this lesson.

© Copyright IBM Corp. 2011 Unit 6. Process Work 6-49

Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
Student Notebook

Complete a work item

Steps to get processing options of a step element

• Determine whether a step element can be reassigned

(and reassign it).

vwStepElement.getCanReassign()
vwStepElement.getCanReassign()
vwStepElement.doReassign(…)
vwStepElement.doReassign(…)

• Determine whether a step element can be returned to the queue

from which the user delegated or reassigned it (and return it).
vwStepElement.getCanReturnToSource()
vwStepElement.getCanReturnToSource()
vwStepElement.doReturnToSource()
vwStepElement.doReturnToSource()

© Copyright IBM Corporation 2011

Figure 6-42. Steps to get processing options of a step element F1561.0

Notes:

6-50 IBM FileNet BPM 5.0: Java API Programming © Copyright IBM Corp. 2011
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
V5.4
Student Notebook

Uempty
Complete a work item
vwStepElement.getCanReassign()

public
public boolean
boolean getCanReassign()
getCanReassign()

• Parameters
–None
• Returns
–A boolean value indicating whether the work item associated with
the step element can be reassigned

© Copyright IBM Corporation 2011

Figure 6-43. vwStepElement.getCanReassign() F1561.0

Notes:

© Copyright IBM Corp. 2011 Unit 6. Process Work 6-51

Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
Student Notebook

Complete a work item

vwStepElement.doReassign(…)
public
public void
void doReassign(String
doReassign(String participant,
participant,
boolean
boolean delegateFlag,String
delegateFlag,String queueName)
queueName)

• Parameters
–participant - Specify the name of the new participant being assigned
to process the step.
–delegateFlag - Specify whether to allow the original participant to
review the completed assignment that was delegated.
–queueName - Specify the queue name to which the work item is to
be moved.
• Returns
–Nothing

© Copyright IBM Corporation 2011

Figure 6-44. vwStepElement.doReassign(...) F1561.0

Notes:
• If queueName is null, the queueName defaults to the current queue of the work item
when that queue is a user-centric queue.
• If queueName is null, the queueName defaults to "Inbox“ when the current queue is a
not a user-centric queue.

6-52 IBM FileNet BPM 5.0: Java API Programming © Copyright IBM Corp. 2011
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
V5.4
Student Notebook

Uempty
Complete a work item
vwStepElement.getCanReturnToSource()
public
public boolean
boolean getCanReturnToSource()
getCanReturnToSource()

• Returns
–A boolean value indicating whether or not the work item associated
with this step element can be returned to its original (source) queue

© Copyright IBM Corporation 2011

Figure 6-45. vwStepElement.getCanReturnToSource() F1561.0

Notes:

© Copyright IBM Corp. 2011 Unit 6. Process Work 6-53

Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
Student Notebook

Complete a work item

vwStepElement.doReturnToSource()
public
public void
void doReturnToSource()
doReturnToSource()

• Parameters
–None
• Returns
–Nothing
• Notes
–Returns the work item to the queue from which a user originally
reassigned or delegated the work item

© Copyright IBM Corporation 2011

Figure 6-46. vwStepElement.doReturnToSource() F1561.0

Notes:

6-54 IBM FileNet BPM 5.0: Java API Programming © Copyright IBM Corp. 2011
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
V5.4
Student Notebook

Uempty
Complete a work item
Sample code to get step element processing options

VWStepElement
VWStepElement stepElement;
stepElement;

if
if (stepElement.getCanViewStatus()){
(stepElement.getCanViewStatus()){
System.out.println("Can
System.out.println("Can View
View Status");
Status");
}}
if
if (stepElement.getCanReassign()){
(stepElement.getCanReassign()){
stepElement.doReassign(“connie",true,
stepElement.doReassign(“connie",true, null);
null);
}}
if
if (stepElement.getCanReturnToSource()){
(stepElement.getCanReturnToSource()){
stepElement.doReturnToSource();
stepElement.doReturnToSource();
}}

© Copyright IBM Corporation 2011

Figure 6-47. Sample code to get step element processing options F1561.0

Notes:

© Copyright IBM Corp. 2011 Unit 6. Process Work 6-55

Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
Student Notebook

Complete a work item

Steps to complete a work item

• Cancel the changes to the work item without advancing it in

the workflow.
vwStepElement.doAbort()
vwStepElement.doAbort()

• Save the changes to the work item without advancing it in the

workflow.
vwStepElement.doSave(…)
vwStepElement.doSave(…)

• Save the changes to the work item and advance it in the

workflow.
vwStepElement.doDispatch()
vwStepElement.doDispatch()

© Copyright IBM Corporation 2011

Figure 6-48. Steps to complete a work item F1561.0

Notes:

6-56 IBM FileNet BPM 5.0: Java API Programming © Copyright IBM Corp. 2011
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
V5.4
Student Notebook

Uempty
Complete a work item
vwStepElement.doSave(…)
public
public void
void doSave(boolean
doSave(boolean unlock)
unlock)

• Parameters
–unlock - Specify whether to unlock the work item after saving it.
• Returns
–Nothing
• Notes
–This method does not advance the work item in the workflow.
–The method throws an exception if an error occurs while the system
attempts to save the work item, or if someone other than the logged-
on user locked the work item.

© Copyright IBM Corporation 2011

Figure 6-49. vwStepElement.doSave(...) F1561.0

Notes:

© Copyright IBM Corp. 2011 Unit 6. Process Work 6-57

Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
Student Notebook

Complete a work item

vwStepElement.doAbort()
public
public void
void doAbort()
doAbort()

• Parameters
–None
• Returns
–Nothing
• Notes
–This method
• Unlocks the work item.
• Does not advance the work item in the workflow.
• Throws an exception if the system cannot unlock the work item.

© Copyright IBM Corporation 2011

Figure 6-50. vwStepElement.doAbort() F1561.0

Notes:

6-58 IBM FileNet BPM 5.0: Java API Programming © Copyright IBM Corp. 2011
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
V5.4
Student Notebook

Uempty
Complete a work item
vwStepElement.doDispatch()
public
public void
void doDispatch
doDispatch ()
()

• Parameters
–None
• Returns
–Nothing
• Notes
–This method
• Saves changes made to the work object associated with this step
element.
• Unlocks the work object.
• Advances the work object in the workflow.

© Copyright IBM Corporation 2011

Figure 6-51. vwStepElement.doDispatch() F1561.0

Notes:

© Copyright IBM Corp. 2011 Unit 6. Process Work 6-59

Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
Student Notebook

Complete a work item

Sample code to complete a work item

• Save changes to the work item without advancing it in the

workflow.
stepElement.doSave(true);
stepElement.doSave(true);

• Cancel changes to the work item without advancing it in the

workflow.
stepElement.doAbort();
stepElement.doAbort();

• Save changes to the work item and advance it in the workflow.

stepElement.doDispatch();
stepElement.doDispatch();

© Copyright IBM Corporation 2011

Figure 6-52. Sample code to complete a work item F1561.0

Notes:
In the sample code, the stepElement variable is of type VWStepElement.

6-60 IBM FileNet BPM 5.0: Java API Programming © Copyright IBM Corp. 2011
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
V5.4
Student Notebook

Uempty
Complete a work item
Demonstrations
• Get processing options of a step element.
• Complete the work item.
–Explore the code sample.
–Run the solution code.
–Observe the results.

© Copyright IBM Corporation 2011

Figure 6-53. Demonstrations F1561.0

Notes:
Demonstration notes
1. Start Eclipse and open the BPMJavaAPISolution project.
2. Review the code for the finishWorkItemEDU (…) method in the ProcessWorkEDU.java
file.
Note: This method contains several tasks, comment out the method calls or the tasks that
you are not testing. You are going to call this method inside the finishWorkItemEDU(…)
method.
3. Run the code and verify the results as instructed in the “Process Work” unit in the
Student Exercises.

© Copyright IBM Corp. 2011 Unit 6. Process Work 6-61

Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
Student Notebook

Complete a work item

Activities
In your Student Exercises
• Unit: Process work
• Lesson: Complete a work item
• Activities:
–Get processing options of a step element.
–Complete the work item.

© Copyright IBM Corporation 2011

Figure 6-54. Activities F1561.0

Notes:
Use your Student Exercises to perform the activities listed.

6-62 IBM FileNet BPM 5.0: Java API Programming © Copyright IBM Corp. 2011
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
V5.4
Student Notebook

Uempty Unit 7. Retrieve Work Status

What this unit is about

This unit describes how to write code using Process Engine Java API
to retrieve and display the workflow history for active and completed
work items and the milestone information.

What you should be able to do

After completing this unit, you should be able to:
• Query work items using Process Administrator
• Retrieve workflow history
• Retrieve workflow history for completed work items
• Retrieve milestones

How you will check your progress

• Successfully complete the activities in the Student Exercises book.

References
www.ibm.com/support/documentation/us/en (Support & downloads
page)
Note: IBM FileNet products belong to the Information Management
product set.

© Copyright IBM Corp. 2011 Unit 7. Retrieve Work Status 7-1

Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
Student Notebook

Retrieve Work Status

Unit lessons
This unit contains the following lessons:
• Retrieve workflow history
• Retrieve milestones

© Copyright IBM Corporation 2011

Figure 7-1. Unit lessons F1561.0

Notes:
Lessons in this unit
This unit has two lessons. After the first lesson, each lesson relies on information and skills
taught in the prior lessons. For best results, do these lessons in the sequence presented.
Retrieve Workflow History – In this lesson, you write code to retrieve the workflow history
and display the information.
Retrieve Milestones – In this lesson, you write code to retrieve the milestone information
and display the information.

7-2 IBM FileNet BPM 5.0: Java API Programming © Copyright IBM Corp. 2011
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
V5.4
Student Notebook

Uempty Lesson 7.1. Retrieve workflow history

© Copyright IBM Corp. 2011 Unit 7. Retrieve Work Status 7-3

Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
Student Notebook

Lesson:
Retrieve workflow history
• Why is this lesson important to you?
– Management at your company wants to collect data on the workflow
history. Your task as their programmer is to write code to retrieve the
workflow history of the following items and display the history.
• How long are workflows taking to complete?
• Which employees are completing tasks?
• Which workflows are currently running?
• What steps are the workflows at?

© Copyright IBM Corporation 2011

Figure 7-2. Lesson: Retrieve workflow history F1561.0

Notes:

7-4 IBM FileNet BPM 5.0: Java API Programming © Copyright IBM Corp. 2011
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
V5.4
Student Notebook

Uempty
Retrieve workflow history
Activities that you need to complete

• Query work items using Process Administrator.

• Retrieve workflow history.
• Retrieve workflow history for completed work items.

© Copyright IBM Corporation 2011

Figure 7-3. Activities that you need to complete F1561.0

Notes:
These are the activities that you are going to perform in this lesson.

© Copyright IBM Corp. 2011 Unit 7. Retrieve Work Status 7-5

Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
Student Notebook

Retrieve workflow history

Steps to retrieve workflow history (Flow)
VWSession 7
VWWorkflowHistory
1 8
VWRoster
VWStepHistory
2
9
VWWorkObject
VWStepOccurrenceHistory
3
VWProcess 10

4 VWStepWorkObjectHistory

VWWorkflowDefinition 11

5 VWParticipantHistory
6
VWMapDefinition Map ID
© Copyright IBM Corporation 2011

Figure 7-4. Steps to retrieve workflow history (Flow) F1561.0

Notes:
This diagram shows the following steps to retrieve workflow history:
1. Get the roster that you want to query.
2. Query the roster and get the individual work object from the query.
3. Retrieve the VWProcess object from the VWWorkObject object.
4. Get the workflow definitions from the VWProcess.
5. Get the maps for each workflow definition.
6. Get the map ID for each map definition.
7. Get the workflow history information for each map.
8. Get the step history objects for each workflow history.
9. Get the step occurrence history objects for each step history object.
10. Get the step work object information for each step occurrence.
11. Get the participant information for each work object.

7-6 IBM FileNet BPM 5.0: Java API Programming © Copyright IBM Corp. 2011
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
V5.4
Student Notebook

Uempty
Retrieve workflow history
Steps to retrieve workflow history (1)

1. Get work objects from roster or queue.

vwRoster.createQuery(…)
vwR oster.createQuery(…)
2. Get VWProcess object from work object.
vwWorkObject.fetchProcess()
vwWorkObject.fetchProcess()
3. Get workflow definitions from the VWProcess.
vwProcess.fetchWorkflowDefinition(…)
vwProcess.fetchWorkflowDefinition(…)
4. Get maps for each workflow definition,.
vwWorkflowDefinition.getMaps()
vwWorkflowDefinition.getMaps()
5. Get map ID and map name for each map definition.
vwMapDefinition[i].getMapId()
vwMapDefinition[i].getMapId()
vwMapDefinition[i].getName()
vwMapDefinition[i].getName()

© Copyright IBM Corporation 2011

Figure 7-5. Steps to retrieve workflow history (1) F1561.0

Notes:

© Copyright IBM Corp. 2011 Unit 7. Retrieve Work Status 7-7

Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
Student Notebook

Retrieve workflow history

Steps to retrieve workflow history (2)

6. Get workflow history information for each map.

vwProcess.fetchWorkflowHistory(…)
vwProcess.fetchWorkflowHistory(…)
7. Get step history objects for each workflow history.
vwWorkflowHistory.next()
vwWorkflowHistory.next()

8. Get step occurrence history objects for each step history object.
vwStepHistory.next()
vwStepHistory.next()
9. Get step work object information for each step occurrence.
vwStepOccurrenceHistory.next()
vwStepOccurrenceHistory.next()
10. Get step work object information for each step occurrence.
vwStepWorkObjectHistory.next()
vwStepWorkObjectHistory.next()
© Copyright IBM Corporation 2011

Figure 7-6. Steps to retrieve workflow history (2) F1561.0

Notes:

7-8 IBM FileNet BPM 5.0: Java API Programming © Copyright IBM Corp. 2011
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
V5.4
Student Notebook

Uempty
Retrieve workflow history
Workflow history information
Get required information
from each object
Status, history, child/split Work Object
information

Launch step comments, launch date,

workflow originator, launch step response

Step name

Step occurrence completion date, date

participant received work, step status

Whether this process was completed

Comments, responses, dates completed and

received, exposed log fields, activity status,
name of participant who completed,
delegated, reassigned, returned, or
terminated step

© Copyright IBM Corporation 2011

Figure 7-7. Workflow history information F1561.0

Notes:
This diagram shows the hierarchical organization of the Process Engine API classes and
the information that you can get from these classes. The object relationships are tree-like:
each object can yield several return objects from the level below it.

© Copyright IBM Corp. 2011 Unit 7. Retrieve Work Status 7-9

Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
Student Notebook

Retrieve workflow history

Java API methods calling sequence

.next() .next()

VWStepHistory VWStepHistory
VWStepOccurrenceHistory VWStepOccurrenceHistory
VWStepWorkObjectHistory VWStepWorkObjectHistory
VWParticipantHistory VWParticipantHistory
x Participant Name x Participant Name
x Step Status x Step Status
x WOB Number x WOB Number
x Comments x Comments

VWWorkflowHistory(int)
© Copyright IBM Corporation 2011

Figure 7-8. Java API methods calling sequence F1561.0

Notes:
This diagram shows the Java API calling sequence for getting the work step history.

7-10 IBM FileNet BPM 5.0: Java API Programming © Copyright IBM Corp. 2011
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
V5.4
Student Notebook

Uempty
Retrieve workflow history
vwWorkObject.fetchProcess()
public
public VWProcess
VWProcess fetchProcess()
fetchProcess()

• Parameters
–None
• Returns
–A VWProcess object that represents the workflow process
containing this work object

© Copyright IBM Corporation 2011

Figure 7-9. vwWorkObject.fetchProcess() F1561.0

Notes:
This method retrieves the VWProcess object from VWWorkObject through Roster Query.
This method cannot be used for work items that are completed or terminated because
VWWorkobject is not available when a workflow is completed.
The next page shows the method that retrieves the VWProcess object from VWSession for
the terminated or completed work item.

© Copyright IBM Corp. 2011 Unit 7. Retrieve Work Status 7-11

Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
Student Notebook

Retrieve workflow history

vwSession.fetchProcess(…)
public
public VWProcess
VWProcess fetchProcess(int
fetchProcess(int workSpaceId,
workSpaceId,
int
int workClassId,String
workClassId,String workflowNumber)
workflowNumber)

• Parameters
– workSpaceId - Specify an integer value that is the workSpaceId associated with
the process.
– workClassId - Specify an integer value that is the workClassId associated with
the process .
– workflowNumber - Specify the workflowNumber associated with the process in a
String.
• Returns
– A VWProcess object that represents the workflow process containing this work
object
• Notes
– This method retrieves the VWProcess object from VWSession for the
terminated or completed work item.

© Copyright IBM Corporation 2011

Figure 7-10. vwSession.fetchProcess(...) F1561.0

Notes:

7-12 IBM FileNet BPM 5.0: Java API Programming © Copyright IBM Corp. 2011
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
V5.4
Student Notebook

Uempty
Retrieve workflow history
vwProcess.fetchWorkflowDefinition(…)
public
public VWWorkflowDefinition
VWWorkflowDefinition
fetchWorkflowDefinition(boolean
fetchWorkflowDefinition(boolean convert)
convert)
• Parameters
–convert – Specify true to convert the fetched workflow definition.
• Returns
–A VWWorkflowDefinition object for this workflow process
• Notes
–If the parameter is specified as false, the returned workflow definition
is in the same form as it was before it was transferred to the server.

© Copyright IBM Corporation 2011

Figure 7-11. vwProcess.fetchWorkflowDefinition(...) F1561.0

Notes:
Convert the workflow definition to ensure that the workflow definition is correct and
complete.
The conversion also checks if the workflow definition references a work class from a former
version of the Process Engine called Panagon Visual WorkFlow.
The workflow definition was defined with a default terminate or malfunction map and the
fetched workflow definition needs to include such a map.
Additional method on this object
public VWWorkflowHistory fetchWorkflowHistory(int instructionSheetID)
Parameters:
instructionSheetID - The integer value for the ID of the workflow map definition object.
Returns:
A workflow history object associated with this workflow process. If no workflow history
exists, the method returns null.

© Copyright IBM Corp. 2011 Unit 7. Retrieve Work Status 7-13

Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
Student Notebook

Retrieve workflow history

vwWorkflowDefinition.getMaps()
public
public VWMapDefinition[]
VWMapDefinition[] getMaps()
getMaps()

• Parameters
–None
• Returns
–An array of VWMapDefinition objects that represent all the workflow
maps associated with this workflow definition

© Copyright IBM Corporation 2011

Figure 7-12. vwWorkflowDefinition.getMaps() F1561.0

Notes:

7-14 IBM FileNet BPM 5.0: Java API Programming © Copyright IBM Corp. 2011
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
V5.4
Student Notebook

Uempty
Retrieve workflow history
vwMapDefinition.getMapId()
public
public int
int getMapId()
getMapId()

• Returns
–An integer that is the value of the map Id Map Map
or –1 to indicate that the map does not have Name ID
a valid map ID Workflow -2
• Notes Terminate -3
–Map IDs are valid only in workflow Malfunction -4
definitions retrieved from the server.
–The reserved map IDs and their associated QueueAsser -5
tionViolation
map names are shown in the table:
Recovery -6
Tracker -7

© Copyright IBM Corporation 2011

Figure 7-13. vwMapDefinition.getMapId() F1561.0

Notes:

© Copyright IBM Corp. 2011 Unit 7. Retrieve Work Status 7-15

Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
Student Notebook

Retrieve workflow history

vwWorkflowHistory.next()
public
public VWStepHistory
VWStepHistory next()
next()

• Returns
–A VWStepHistory object that represents a unique history event for
the step.
• Notes
–Retrieves the subsequent element for this VWWorkflowHistory
instance.
–Invoke this method repeatedly to retrieve a series of VWStepHistory
objects.
–Returns null when no more objects can be returned.

© Copyright IBM Corporation 2011

Figure 7-14. vwWorkflowHistory.next() F1561.0

Notes:

7-16 IBM FileNet BPM 5.0: Java API Programming © Copyright IBM Corp. 2011
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
V5.4
Student Notebook

Uempty
Retrieve workflow history
vwStepHistory.next()
public
public VWStepHistory
VWStepHistory next()
next()

• Returns
–A VWStepOccurrenceHistory object that represents an element
containing history information. If no more items exist, the method
returns null.
• Notes
–This method requires a buffer on the collection greater than 1 to
operate properly. The default buffer size is 50

© Copyright IBM Corporation 2011

Figure 7-15. vwStepHistory.next() F1561.0

Notes:
Additional method on this object
public boolean hasNext()
public String getStepName()

© Copyright IBM Corp. 2011 Unit 7. Retrieve Work Status 7-17

Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
Student Notebook

Retrieve workflow history

vwStepOccurrenceHistory.next()
public
public VWStepObjectHistory
VWStepObjectHistory next()
next()

• Parameters
–None
• Returns
–A VWStepWorkObjectHistory object that contains a history of the
work objects for a step item

© Copyright IBM Corporation 2011

Figure 7-16. vwStepOccurrenceHistory.next() F1561.0

Notes:
Additional method on this object
public boolean hasNext()
public Date getCompletionDate()
public Date getDateReceived()

7-18 IBM FileNet BPM 5.0: Java API Programming © Copyright IBM Corp. 2011
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
V5.4
Student Notebook

Uempty
Retrieve workflow history
vwStepWorkObjectHistory.next()
public
public VWParticipantHistory
VWParticipantHistory next()
next()

• Parameters
–None
• Returns
–A VWParticipantHistory object that contains the participant history
for a step element

© Copyright IBM Corporation 2011

Figure 7-17. vwStepWorkObjectHistory.next() F1561.0

Notes:

© Copyright IBM Corp. 2011 Unit 7. Retrieve Work Status 7-19

Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
Student Notebook

Retrieve workflow history

vwParticipantHistory.getUserName()
public
public String
String getUserName()
getUserName()

• Parameters
–None
• Returns
–A String, which is the name of the participant who completed,
reassigned, or delegated the work object for the current step.

© Copyright IBM Corporation 2011

Figure 7-18. vwParticipantHistory.getUserName() F1561.0

Notes:

7-20 IBM FileNet BPM 5.0: Java API Programming © Copyright IBM Corp. 2011
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
V5.4
Student Notebook

Uempty
Retrieve workflow history
Sample code to retrieve workflow history (1)

VWRoster
VWRoster roster
roster == myPESession.getRoster(rosterName);
myPESession.getRoster(rosterName);
int
int queryFlag = VWRoster.QUERY_NO_OPTIONS; String
queryFlag = VWRoster.QUERY_NO_OPTIONS; String
filters = "LoanName='Alva Edison'and F_TrackerStatus=0";
filters = "LoanName='Alva Edison'and F_TrackerStatus=0";
VWRosterQuery
VWRosterQuery rosterQuery
rosterQuery == roster.createQuery(null,
roster.createQuery(null,
null,
null, null, queryFlag, filters,
null, queryFlag, filters, null,
null,
VWFetchType.FETCH_TYPE_WORKOBJECT);
VWFetchType.FETCH_TYPE_WORKOBJECT);
while
while (rosterQuery.hasNext())
(rosterQuery.hasNext()) {{
VWWorkObject
VWWorkObject rosterElement
rosterElement == (VWWorkObject)
(VWWorkObject)
rosterQuery.next();
rosterQuery.next();
VWProcess process = rosterElement.fetchProcess();
VWProcess process = rosterElement.fetchProcess();
VWWorkflowDefinition
VWWorkflowDefinition workflowDefinition
workflowDefinition ==
process.fetchWorkflowDefinition(false);
process.fetchWorkflowDefinition(false);
VWMapDefinition[]
VWMapDefinition[] mapsmaps == workflowDefinition.getMaps();
workflowDefinition.getMaps();
for
for (int i = 0; i < maps.length; i++)
(int i = 0; i < maps.length; i++) {{
System.out.println("Map
System.out.println("Map Name:Name: "" ++ maps[i].getName());
maps[i].getName());
int mapID = maps[i].getMapId();
int mapID = maps[i].getMapId();
……

© Copyright IBM Corporation 2011

Figure 7-19. Sample code to retrieve workflow history (1) F1561.0

Notes:

© Copyright IBM Corp. 2011 Unit 7. Retrieve Work Status 7-21

Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
Student Notebook

Retrieve workflow history

Sample code to retrieve workflow history (2)

System.out.println("Map
System.out.println("Map Id:
Id: "" ++ mapID);
mapID);
VWWorkflowHistory
VWWorkflowHistory workflowHistory ==
workflowHistory
process.fetchWorkflowHistory(mapID);
process.fetchWorkflowHistory(mapID);
System.out.println("Originator:
System.out.println("Originator: "" ++
workflowHistory.getOriginator());
workflowHistory.getOriginator());
System.out.println("<stepHistory
System.out.println("<stepHistory Info>");
Info>");
while
while (workflowHistory.hasNext())
(workflowHistory.hasNext()) {{
VWStepHistory
VWStepHistory stepHistory
stepHistory == workflowHistory.next();
workflowHistory.next();
System.out.println(stepHistory.getStepName());
System.out.println(stepHistory.getStepName());
System.out.println("\t<stepOccurenceHistory Info>");
System.out.println("\t<stepOccurenceHistory Info>");
while
while (stepHistory.hasNext())
(stepHistory.hasNext()) {{
VWStepOccurrenceHistory
VWStepOccurrenceHistory stepOccurenceHistory
stepOccurenceHistory ==
stepHistory.next();
stepHistory.next();
System.out.println("\tDate
System.out.println("\tDate received:
received: "" ++
stepOccurenceHistory.getDateReceived()
stepOccurenceHistory.getDateReceived() ++ "</Date
"</Date
received>");
received>");
…
…
© Copyright IBM Corporation 2011

Figure 7-20. Sample code to retrieve workflow history (2) F1561.0

Notes:

7-22 IBM FileNet BPM 5.0: Java API Programming © Copyright IBM Corp. 2011
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
V5.4
Student Notebook

Uempty
Retrieve workflow history
Sample code to retrieve workflow history (3)

System.out.println("\tDate
System.out.println("\tDate completed:
completed: "" ++
stepOccurenceHistory.getCompletionDate()
stepOccurenceHistory.getCompletionDate() ++ "</Date
"</Date
completed>");
completed>");
System.out.println("\t\t<stepWorkObjectHistory Info>");
System.out.println("\t\t<stepWorkObjectHistory Info>");
while (stepOccurenceHistory.hasNext())
while (stepOccurenceHistory.hasNext()) { {
VWStepWorkObjectHistory
VWStepWorkObjectHistory stepWorkObjectHistory
stepWorkObjectHistory ==
stepOccurenceHistory.next();
stepOccurenceHistory.next();
System.out.println("\t\t\t<ParticipantHistory Info>");
System.out.println("\t\t\t<ParticipantHistory Info>");
while (stepWorkObjectHistory.hasNext())
while (stepWorkObjectHistory.hasNext()) { {
VWParticipantHistory
VWParticipantHistory participantHistory
participantHistory ==
stepWorkObjectHistory.next();
stepWorkObjectHistory.next();
System.out.println("\t\t\tDate
System.out.println("\t\t\tDate received
received == "" ++
participantHistory.getDateReceived()+"</Date
participantHistory.getDateReceived()+"</Date received>");
received>");
System.out.println("\t\t\tComments =
System.out.println("\t\t\tComments = " +" +
participantHistory.getComments()
participantHistory.getComments() ++ "</Comments>");
"</Comments>");
System.out.println("\t\t\tUser
System.out.println("\t\t\tUser == "" ++
participantHistory.getUserName()+ "</User>");
participantHistory.getUserName()+ "</User>");
……
© Copyright IBM Corporation 2011

Figure 7-21. Sample code to retrieve workflow history (3) F1561.0

Notes:

© Copyright IBM Corp. 2011 Unit 7. Retrieve Work Status 7-23

Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
Student Notebook

Retrieve workflow history

Sample code to retrieve workflow history (4)

System.out.println("\t\t\tParticipant
System.out.println("\t\t\tParticipant == "" ++
participantHistory.getParticipantName()
participantHistory.getParticipantName() ++
"</Participant>");
"</Participant>");
}} //
// while
while stepWorkObjectHistory
stepWorkObjectHistory
System.out.println("\t\t\t
System.out.println("\t\t\t
</ParticipantHistory Info>");
</ParticipantHistory Info>");
}} // while stepOccurenceHistory
// while stepOccurenceHistory
System.out.println("\t\t</stepWorkObjectHistory
System.out.println("\t\t</stepWorkObjectHistory
Info>");
Info>");
}} // while stepHistory
// while stepHistory
System.out.println("\t</stepOccurenceHistoryInfo>");
System.out.println("\t</stepOccurenceHistoryInfo>");
}} //
// while
while workflowHistory
workflowHistory
}} //
// for
for Workflow
Workflow maps
maps
}} //
// while
while rosterQuery
rosterQuery hasnext()
hasnext()

© Copyright IBM Corporation 2011

Figure 7-22. Sample code to retrieve workflow history (4) F1561.0

Notes:

7-24 IBM FileNet BPM 5.0: Java API Programming © Copyright IBM Corp. 2011
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
V5.4
Student Notebook

Uempty
Retrieve workflow history
Demonstrations
• Query work items using Process Administrator
• Retrieve workflow history
• Retrieve workflow history for completed work items
–Explore the code sample.
–Run the solution code.
–Observe the results.

© Copyright IBM Corporation 2011

Figure 7-23. Demonstrations F1561.0

Notes:
Demonstration notes - 1
Query work items using Process Administrator
Do the following steps and verify the results as instructed in the “Retrieve Work Status” unit
in the Student Exercises.
1. Launch the workflow and set the value for the subject.
2. Query the work items using Process Administrator.
3. Process the step by opening the step processor for the work item.
Demonstration notes- 2
Retrieve workflow history
1. Start Eclipse and open the BPMJavaAPISolution project.
2. Review the code for retrieving the workflow history in the getWorkflowHistoryEDU (…)
method in the RetrieveWorkStatusEDU.java file.

© Copyright IBM Corp. 2011 Unit 7. Retrieve Work Status 7-25

Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
Student Notebook

Note: The code for this task ends just before the
process.fetchReachedWorkflowMilestones(…) method call.
3. Run the code and verify the results as instructed in the “Retrieve Work Status” unit in
the Student Exercises.
Demonstration notes - 3
Retrieve workflow history for completed work items
Repeat steps 1 through 3 in Demonstration 2 for the
getCompletedWorkItemWorkflowHistoryEDU (…) method.

7-26 IBM FileNet BPM 5.0: Java API Programming © Copyright IBM Corp. 2011
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
V5.4
Student Notebook

Uempty
Retrieve workflow history
Activities
In your Student Exercises
• Unit: Process work
• Lesson: Retrieve workflow history
• Activities:
–Query work items using Process Administrator
–Retrieve workflow history
–Retrieve workflow history for completed work items

© Copyright IBM Corporation 2011

Figure 7-24. Activities F1561.0

Notes:
Use your Student Exercises to perform the activities listed.

© Copyright IBM Corp. 2011 Unit 7. Retrieve Work Status 7-27

Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
Student Notebook

7-28 IBM FileNet BPM 5.0: Java API Programming © Copyright IBM Corp. 2011
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
V5.4
Student Notebook

Uempty Lesson 7.2. Retrieve milestones

© Copyright IBM Corp. 2011 Unit 7. Retrieve Work Status 7-29

Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
Student Notebook

Lesson:
Retrieve milestones
• Why is this lesson important to you?
– Management at your company wants to get information about which
milestones have been reached on currently running workflows. Your
task as their programmer is to write code to retrieve the milestone
information and display it.

© Copyright IBM Corporation 2011

Figure 7-25. Lesson: Retrieve milestones F1561.0

Notes:

7-30 IBM FileNet BPM 5.0: Java API Programming © Copyright IBM Corp. 2011
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
V5.4
Student Notebook

Uempty
Retrieve milestones
Activities that you need to complete

• Retrieve milestones.

© Copyright IBM Corporation 2011

Figure 7-26. Activities that you need to complete F1561.0

Notes:
These are the activities that you are going to perform in this lesson.

© Copyright IBM Corp. 2011 Unit 7. Retrieve Work Status 7-31

Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
Student Notebook

Retrieve milestones
Steps to display milestone history information

1. Get work objects from the roster or queue.

vwRoster.createQuery(…)
vwRoster.createQuery(…)
2. Get VWProcess object from the work object.
vwWorkObject.fetchProcess()
vwWorkObject.fetchProcess()
3. Get reached milestones from the VWProcess object.
vwProcess.fetchReachedWorkflowMilestones(…)
vwProcess.fetchReachedWorkflowMilestones(…)
4. For each milestone, get milestone element information.
vwWorkflowMilestones.next()
vwWorkflowMilestones.next()
5. Display information for each milestone element.
vwMilestoneElement.getMessage()
vwMilestoneElement.getMessage()
© Copyright IBM Corporation 2011

Figure 7-27. Steps to display milestone history information F1561.0

Notes:

7-32 IBM FileNet BPM 5.0: Java API Programming © Copyright IBM Corp. 2011
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
V5.4
Student Notebook

Uempty
Retrieve milestones
vwProcess.fetchReachedWorkflowMilestones(…)

public
public VWWorkflowMilestones
VWWorkflowMilestones
fetchReachedWorkflowMilestones(int
fetchReachedWorkflowMilestones(int theLevel)
theLevel)
• Parameters
–theLevel – Specify an integer value that is the criterion, milestone
event level.
• Milestone events whose level value is less than or equal to this
value are fetched from the event log.
• Returns
–A VWWorkflowMilestones (an iterator) object associated with this
workflow process

© Copyright IBM Corporation 2011

Figure 7-28. vwProcess.fetchReachedWorkflowMilestones(...) F1561.0

Notes:

© Copyright IBM Corp. 2011 Unit 7. Retrieve Work Status 7-33

Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
Student Notebook

Retrieve milestones
vwWorkflowMilestones.next()
public
public VWMilestoneElement
VWMilestoneElement next()
next()

• Parameters
–None
• Returns
–A VWMilestoneElement object (a milestone occurrence) that
represents a unique milestone for the step. If no more items exist,
the method returns null.

© Copyright IBM Corporation 2011

Figure 7-29. vwWorkflowMilestones.next() F1561.0

Notes:
Additional method on this object
public boolean hasNext()

7-34 IBM FileNet BPM 5.0: Java API Programming © Copyright IBM Corp. 2011
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
V5.4
Student Notebook

Uempty
Retrieve milestones
vwMilestoneElement.getMessage()
public
public String
String getMessage()
getMessage()

• Parameters
–None
• Returns
–The message logged for this milestone event.
–Can be null.

© Copyright IBM Corporation 2011

Figure 7-30. vwMilestoneElement.getMessage() F1561.0

Notes:
Additional method on this object
public String getName()
public Date getTimestamp()

© Copyright IBM Corp. 2011 Unit 7. Retrieve Work Status 7-35

Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
Student Notebook

Retrieve milestones
Sample code to retrieve milestone information

• Iterate through all of the milestones for this object.

int
int level
level == 1;
1;
VWWorkflowMilestones
VWWorkflowMilestones milestones
milestones ==
process.fetchReachedWorkflowMilestones(level);
process.fetchReachedWorkflowMilestones(level);

• Get milestone element information.

while
while (milestones.hasNext())
(milestones.hasNext()) {{
VWMilestoneElement
VWMilestoneElement milestoneElement
milestoneElement ==
milestones.next();
milestones.next();
System.out.println("Name:
System.out.println("Name: "" ++
milestoneElement.getName());
milestoneElement.getName());
System.out.println("Message:
System.out.println("Message: "" ++
milestoneElement.getMessage());
milestoneElement.getMessage());
System.out.println("Time
System.out.println("Time logged:
logged: "" ++
milestoneElement.getTimestamp());
milestoneElement.getTimestamp());

© Copyright IBM Corporation 2011

Figure 7-31. Sample code to retrieve milestone information F1561.0

Notes:

7-36 IBM FileNet BPM 5.0: Java API Programming © Copyright IBM Corp. 2011
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
V5.4
Student Notebook

Uempty
Retrieve milestones
Demonstrations
• Retrieve milestones
–Explore the code sample.
–Run the solution code.
–Observe the results.

© Copyright IBM Corporation 2011

Figure 7-32. Demonstrations F1561.0

Notes:
Demonstration notes
1. Start Eclipse and open the BPMJavaAPISolution project.
2. Review the code for retrieving the milestones in the getWorkflowHistoryEDU(…)
method in the RetrieveWorkStatusEDU.java file.
Note: The code for this task is at the end of the method starting with the
process.fetchReachedWorkflowMilestones(…) method call.
3. Run the code and verify the results as instructed in the “Retrieve Work Status” unit in
the Student Exercises.

© Copyright IBM Corp. 2011 Unit 7. Retrieve Work Status 7-37

Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
Student Notebook

Retrieve milestones
Activities
In your Student Exercises
• Unit: Process work
• Lesson: Retrieve milestones
• Activities:
– Retrieve milestones.

© Copyright IBM Corporation 2011

Figure 7-33. Activities F1561.0

Notes:
Use your Student Exercises to perform the activities listed.

7-38 IBM FileNet BPM 5.0: Java API Programming © Copyright IBM Corp. 2011
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
V5.4
Student Notebook

Uempty Unit 8. Work with Component Integrator

What this unit is about

This unit describes how to implement the IBM FileNet-provided
component CE_Operations, configure a Component Manager, write
code for a Java component, configure a Java component queue, and
configure a JMS component queue.

What you should be able to do

After completing this unit, you should be able to:
• Implement CE_Operations in a workflow.
• Create and configure a component manager.
• Create a Java file for component.
• Create a Java archive file for deployment as a component.
• Create and configure a Java component queue.

How you will check your progress

• Successfully complete the activities in the Student Exercises book.

References
www.ibm.com/support/documentation/us/en (Support & downloads
page)
Note: IBM FileNet products belong to the Information Management
product set.

© Copyright IBM Corp. 2011 Unit 8. Work with Component Integrator 8-1
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
Student Notebook

Work with Component Integrator

Unit lessons
This unit contains the following lessons:
• Component integration concepts
• Create and configure a Component Manager
• Configure a Java component queue
Appendix:
• Configure component queues for JMS

© Copyright IBM Corporation 2011

Figure 8-1. Unit lessons F1561.0

Notes:
Lessons in this unit
This unit has four lessons. After the first lesson, each lesson relies on information and skills
taught in the prior lessons. For best results, do these lessons in the sequence presented.
Component integration concepts – In this lesson, you use the IBM FileNet-provided
component CE_Operations to fetch the information and populate the workflow.
Create and configure a Component Manager – In this lesson, you configure a
Component Manager and launch a workflow to test the component.
Configure a Java component queue – In this lesson, you write code for a Java
component, configure a component queue, and test the component using a workflow.
This unit has one appendix containing additional information:
Configure component queues for JMS

8-2 IBM FileNet BPM 5.0: Java API Programming © Copyright IBM Corp. 2011
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
V5.4
Student Notebook

Uempty Lesson 8.1. Component integration concepts

© Copyright IBM Corp. 2011 Unit 8. Work with Component Integrator 8-3
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
Student Notebook

Lesson:
Component integration concepts
• Why is this lesson important to you?
–You are launching a workflow to send product details to a
customer. The product details are contained in a document
stored on the IBM FileNet P8 Content Engine. You are going to
use the IBM FileNet-provided component CE_Operations to
fetch the information and populate the workflow.

© Copyright IBM Corporation 2011

Figure 8-2. Lesson: Component integration concepts F1561.0

Notes:
The solution architect at your company has prepared a design for a workflow solution. The
solution includes automated tasks performed by Java and JMS components. As their
programmer, you are going to write code for these process components. In order to
communicate with the solution architect effectively about the requirements, you must be
familiar with Component Integrator and the configuration tasks required to integrate
process components with the FileNet BPM solution.

8-4 IBM FileNet BPM 5.0: Java API Programming © Copyright IBM Corp. 2011
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
V5.4
Student Notebook

Uempty
Component integration concepts
Activities that you need to complete

• Implement CE_Operations in a workflow.

© Copyright IBM Corporation 2011

Figure 8-3. Activities that you need to complete F1561.0

Notes:
These are the activities that you are going to perform in this lesson.

© Copyright IBM Corp. 2011 Unit 8. Work with Component Integrator 8-5
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
Student Notebook

Component integration concepts

About Component Integrator
• IBM FileNet P8 Platform service that does the following:
–Connects the Process Engine with an external system
–Provides basic Enterprise Information System (EIS) integration
• Elements of IBM FileNet BPM component integration
–Component Manager on the Application Engine
–Component adaptors on the Application Engine
–Component queues on the Process Engine
–CE_Operations: a component included with the product to integrate
Content Engine and Process Engine

© Copyright IBM Corporation 2011

Figure 8-4. About Component Integrator F1561.0

Notes:
Help path
• IBM FileNet P8 Version 5.0 Information Center > Integrating workflow into document
management > Process applications concepts > Designing and running workflows >
About the Component Integrator
Definition: The Component Integrator is a functionality (software services) that is provided
in a FileNet BPM system. It makes interaction with an external entity, such as a Java object
or JMS messaging system, possible from a workflow step.
The Component Integrator provides an application integration capability for interacting with
a component (Java or JMS queue) from a workflow step. The Component Integrator is an
IBM FileNet P8 service that connects the Process Engine with an external system.
The Component Integrator makes importing custom Java components possible, and
makes custom components available in a workflow. In the workflow definition, a component
step connects to a component queue configured for one or more operations in the external
component.

8-6 IBM FileNet BPM 5.0: Java API Programming © Copyright IBM Corp. 2011
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
V5.4
Student Notebook

Uempty • Component Managers: These services run on the Application Engine and connect a
work item with its appropriate Java or JMS service adaptor.
• Configuration: Configure the component queues using Process Configuration Console.
• CE_Operations (a component queue provided with the product) is one of the default
objects created when an isolated region is initialized. CE_Operations can be configured
to integrate functionality between workflows and Content Engine object store objects.

© Copyright IBM Corp. 2011 Unit 8. Work with Component Integrator 8-7
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
Student Notebook

Component integration concepts

Purposes for component integration
• Extend business functionality easily without full application
development.
• Automate work processing.
• Perform external functions from within a workflow.
• Use existing Java business objects and components.
• Integrate with a Java Message Service (JMS).

© Copyright IBM Corporation 2011

Figure 8-5. Purposes for component integration F1561.0

Notes:
Help path
• IBM FileNet P8 Version 5.0 Information Center > Administering IBM FileNet P8 >
Administering Process Engine > Workflow administration tasks > Configure optional
features > Configure the Component Integrator

8-8 IBM FileNet BPM 5.0: Java API Programming © Copyright IBM Corp. 2011
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
V5.4
Student Notebook

Uempty
Component integration concepts
Components Behavior
• A component is a “work performer” application.
–Used to process workflow data.
–Typically has no user interface.
–Typically performs automatic operations on work items.
• A work item waits in a component queue for processing.
–The work item makes a request of a component.
–The component can perform other actions outside the region.
–The component can provide a response.

Component queue 1. Request (2+2=?)

2. action (log “2+2=4”)
3. Response (4) Component
Work item

© Copyright IBM Corporation 2011

Figure 8-6. Components Behavior F1561.0

Notes:
Help path
• IBM FileNet P8 Version 5.0 Information Center > Developing IBM FileNet P8
applications > Process Engine Development > Process Java Developer's Guide >
Developing Process Applications > Developing Work Performers > Developing
Component Integrator-Based Work Performers
Components typically perform automated functions that do not require human intervention.
The activity is initiated by the work item, which sends data to the component as a request.
The component might return a response from the request if it is configured to do so, or it
might perform some function outside the process region, such as filing a document in an
object store. Both behaviors are optional.
For example, if a work item needs to know the sum of two numbers, it can send them to a
component that performs addition. The component can send the sum back to the work
item, or it can send the sum (or the original parameters) elsewhere, as the application
demands.

© Copyright IBM Corp. 2011 Unit 8. Work with Component Integrator 8-9
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
Student Notebook

Definition: A component queue is a queue that holds work items. These work items can be
completed by an external entity that interacts with the workflow using the Component
Integrator.

8-10 IBM FileNet BPM 5.0: Java API Programming © Copyright IBM Corp. 2011
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
V5.4
Student Notebook

Uempty
Component integration concepts
Component Integrator architecture
Process Designer
Process Engine
Component Queues 2
JMS Java Java Java

Process Configuration 4
JMS Adaptor Message Queue
Console JMS Adaptor
6
Java Adaptor Java Component1
Component Java Adaptor
1 Manager

Java Adaptor Java Component2

Java Adaptor
3 5
7
JMS Java Java Adaptor Java Component3
Java Adaptor
Config Config
JAR/Class
File

© Copyright IBM Corporation 2011

Figure 8-7. Component Integrator architecture F1561.0

Notes:
The diagram contains the following Component Integrator operation steps:
1. Import queue and operation definitions using the Process Configuration Console.
2. Create workflow definitions with Process Designer and leverage imported queue and
operation definitions.
3. Start and monitor the Component Manager with Process Task Manager.
4. The connector subsystem pulls items from the relevant queues.
5. Based on the associated service descriptor, the connector subsystem passes that item
on to an appropriate adaptor.
6. The adaptor establishes a connection to an external system and executes the
associated interface.
7. The adaptor waits for a response (except in the JMS case), updates the work item, and
dispatches it.

© Copyright IBM Corp. 2011 Unit 8. Work with Component Integrator 8-11
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
Student Notebook

Component integration concepts

Components and the isolated region
• Component queues reside in the isolated region.
• Component Integrator on the Application Engine handles
–Component manager and component adaptors

Application Engine Process Engine

Component Integrator Isolated Region

Component Component Event

Roster
Log
Component
queues
Adaptor Adaptor Work
item Inbox

Component Other
Manager queues

© Copyright IBM Corporation 2011

Figure 8-8. Components and the isolated region F1561.0

Notes:
Help path
• IBM FileNet P8 Information Center > Administering IBM FileNet P8 > Administering
Process Engine > Workflow administration tasks > Configure optional features >
Configure the Component Integrator
On the Application Engine:
• The Component Integrator enables a workflow step to interact with an external entity,
that is, a component, such as a Java object or JMS messaging system.
• A Component Manager is a subsystem that coordinates one or more components and
links them to a process region. This service runs on the Application Engine or web
server and connects a work item with its appropriate Java or JMS service adaptor. One
or more Component Managers can be running in a BPM system.
• An adaptor is an interface that communicates events from the Process Engine to
external components, such as Java objects or JMS messaging systems. Adaptors are

8-12 IBM FileNet BPM 5.0: Java API Programming © Copyright IBM Corp. 2011
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
V5.4
Student Notebook

Uempty part of the Component Integrator. Solution builders configure the adaptor for each
component.
On the Process Engine:
• A component queue holds work items that can be completed by an external entity.
Methods in the external entity are exposed to the work items as component queue
operations. Solution builders configure the component queue and its operations.
• The solution builder can configure one or more component queues in an isolated
region.
• The built-in component queue is called CE_Operations and provides interaction with
objects in a Content Engine object store.
This relationships among these components are illustrated in the diagram. Solution
builders configure the diagram elements shown in blue: Components, Adaptors,
Component Manager, and Component Queues.

© Copyright IBM Corp. 2011 Unit 8. Work with Component Integrator 8-13
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
Student Notebook

Component integration concepts

Types of components
• Java component
–Component functionality is provided by a Java archive file.
–Java classes contain methods (operations) to perform the work.
–Data can move in both directions:
• From the isolated region to the component
• From the component to the isolated region
–Uses a configured Java component adaptor
• JMS component
–Component functionality sends a message to a specified queue.
–Data moves only from the isolated region to the JMS queue.
–A configured JMS component adaptor is used.

© Copyright IBM Corporation 2011

Figure 8-9. Types of components F1561.0

Notes:
Help path
• IBM FileNet P8 Information Center > Integrating workflow into document management
> Process Designer > About steps > About component steps
Java and JMS are the two types of components that a component queue can use. Both
types of components use a service adaptor to communicate to the Process Engine.
Java
Java objects are archived classes or collections of classes that perform a function. IBM
FileNet P8 provides a Java component named CE_Operations to provide workflow
definitions programmatic access to Content Engine objects.
The Java adaptor allows the solution builder to expose public methods from a Java class
as operations on a queue.

8-14 IBM FileNet BPM 5.0: Java API Programming © Copyright IBM Corp. 2011
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
V5.4
Student Notebook

Uempty JMS
The Java Message Service (JMS) was designed to develop business applications that
asynchronously send and receive business data and events.
JMS components work only with Workplace or Workplace XT and are write-only (from the
workflow to the JMS queue).
The JMS adaptor allows you to publish workflow data to a JMS queue, using operations.

© Copyright IBM Corp. 2011 Unit 8. Work with Component Integrator 8-15
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
Student Notebook

Component integration concepts

Content Extended operations (CE_Operations)
• IBM FileNet uses the component integrator infrastructure to
provide CE_Operations.
• Use CE_Operations in a workflow definition
–To facilitate manipulation of documents and other objects in an object
store
• Available CE_Operations
–File a document in an object store folder
–Unfile a document from an object store folder
–Publish a document using a publishing template
–Get property values of a document or folder
(integer, float, date, boolean, string)
–Set property value of a document or folder
(integer, float, date, boolean, string)

© Copyright IBM Corporation 2011

Figure 8-10. Content Extended operations (CE_Operations) F1561.0

Notes:
Help path
• IBM FileNet P8 Version 5.0 Information Center > Integrating workflow into document
management > Process applications concepts > Designing and running workflows >
Using Content Extended Operations in a workflow definition
To use CE_Operations, you need to understand the properties of documents in an object
store.
• Each document in an object store has a set of properties defined by the system.
Example: the display name (the name of the document), the creator, the date last
modified, and so on.
• In addition, each document is associated with a particular document class that usually
defines additional properties specific to that type of document.
Note: The Content Java API and Content Engine object properties are covered in a
separate course.

8-16 IBM FileNet BPM 5.0: Java API Programming © Copyright IBM Corp. 2011
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
V5.4
Student Notebook

Uempty
Component integration concepts
Steps to use CE_Operations in a workflow
1. In Process Configuration Console, set CE_Operations
properties
2. Determine the symbolic name and data type of the object
class property.
– Use Content Engine Enterprise Manager.
3. In the workflow definition, define the appropriate attachments
and data fields.
– This data field holds the value that is retrieved from the object
property in the component step.
4. On the workflow map, add the component step.
– Select CE_Operations, and define the appropriate parameters for
each operation.

© Copyright IBM Corporation 2011

Figure 8-11. Steps to use CE_Operations in a workflow F1561.0

Notes:
Help paths
• IBM FileNet P8 Version 5.0 Information Center > Integrating workflow into document
management > Process applications concepts > Designing and running workflows >
Using Content Extended Operations in a workflow definition
• IBM FileNet P8 Information Center > Integrating workflow into document management
> Process Configuration Console > About queues > Manage component queues >
Enable Content Extended Operations

© Copyright IBM Corp. 2011 Unit 8. Work with Component Integrator 8-17
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
Student Notebook

Component integration concepts

Demonstrations
• Implement CE_Operations in a workflow.

© Copyright IBM Corporation 2011

Figure 8-12. Demonstrations F1561.0

Notes:
Demonstration notes
This demonstration shows you a simple workflow with a component step using Process
Designer.
1. Log in to Workplace XT as the Administrator user.
2. Go to the Tools > Advanced Tools > Process Designer. Process Designer opens.
3. In Process Designer, open and review a workflow using the data and the instructions in
the “Component integration concepts” lesson of the “Work with Component Integrator”
unit in the Student Exercises.
4. Close Process Designer applet window.

8-18 IBM FileNet BPM 5.0: Java API Programming © Copyright IBM Corp. 2011
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
V5.4
Student Notebook

Uempty
Component integration concepts
Activities
In your Student Exercises
• Unit: Work with Component Integrator
• Lesson: Component integration concepts
• Activities:
– Implement CE_Operations in a workflow.

© Copyright IBM Corporation 2011

Figure 8-13. Activities F1561.0

Notes:
Use your Student Exercises to perform the activities listed.

© Copyright IBM Corp. 2011 Unit 8. Work with Component Integrator 8-19
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
Student Notebook

8-20 IBM FileNet BPM 5.0: Java API Programming © Copyright IBM Corp. 2011
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
V5.4
Student Notebook

Uempty Lesson 8.2. Create and configure a Component Manager

© Copyright IBM Corp. 2011 Unit 8. Work with Component Integrator 8-21
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
Student Notebook

Lesson:
Create and configure a Component Manager
• Why is this lesson important to you?
– You need to configure a Component Manager to integrate the
components with its CE_Operations component queue.

© Copyright IBM Corporation 2011

Figure 8-14. Lesson: Create and configure a Component Manager F1561.0

Notes:

8-22 IBM FileNet BPM 5.0: Java API Programming © Copyright IBM Corp. 2011
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
V5.4
Student Notebook

Uempty
Create and configure a Component Manager
Activities that you need to complete

• Create and configure a Component Manager.

© Copyright IBM Corporation 2011

Figure 8-15. Activities that you need to complete F1561.0

Notes:
These are the activities that you are going to perform in this lesson.

© Copyright IBM Corp. 2011 Unit 8. Work with Component Integrator 8-23
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
Student Notebook

Create and configure a Component Manager

About Component Manager
• A subsystem that provides a link between Process Engine and
external systems.
–It coordinates component interaction.
–It delivers events from Process Engine to external entities, such as
the following entities:
• Web service
• Messaging system
• Content Engine
• The Process Engine server connection to Component
Manager must be configured.
–The connection is usually configured at installation time.
• Component manager must be configured.

© Copyright IBM Corporation 2011

Figure 8-16. About Component Manager F1561.0

Notes:
Help path
• IBM FileNet P8 Information Center > Administering IBM FileNet P8 > Working with
Process Task Manager > Component Manager
A Component Manager provides a link between the Process Engine and external systems
using a variety of interfaces.
A Component Manager coordinates one or more components, which are responsible for
delivering events from the Process Engine to an external entity such as a web service or
messaging system. You can run one or more Component Managers. Each Component
Manager coordinates one or more components.
Through Process Task Manager, you can configure the system to poll periodically for new
events or to automatically respond to new events when they occur.

8-24 IBM FileNet BPM 5.0: Java API Programming © Copyright IBM Corp. 2011
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
V5.4
Student Notebook

Uempty
Create and configure a Component Manager
Reasons for multiple Component Managers
• The need to start, stop, and administer components separately
• Performance and resource allocation considerations
• Component queues that have different configuration requirements must
be configured in separate Component Managers.
– Java libraries versus JMS libraries
– Different security requirements
• The need for multiple Workplace XT applications
• The need for multiple Content Engines

© Copyright IBM Corporation 2011

Figure 8-17. Reasons for multiple Component Managers F1561.0

Notes:
You can have as many Component Managers as needed for each region.
Component Manager uses a Process Engine connection point to access Process Engine.
Connection points are stored on the Content Engine server. Before Component Manager
can access a connection point, you must specify the information Process Task Manager
(PTM) uses to connect to Content Engine.
The component queues associated with a Component Manager distinguish it from other
Component Managers. By default, when you create a new Component Manager, all the
component queues in the selected region that are not already assigned to another
component queue are assigned to the new Component Manager.
The screen capture shows an example of multiple Component Managers running in PTM.
The PELoanRegion.All Component Manager manages the CE_Operations and
WSRequest(0) queues in the PELoanRegion isolated region. The
PEConnection.LoanInfoCalculation Component Manager manages the
LoanInfoCalculation queue in the PEConnection isolated region.

© Copyright IBM Corp. 2011 Unit 8. Work with Component Integrator 8-25
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
Student Notebook

Create and configure a Component Manager

How to create a new Component Manager
• Use Process Task Manager on the Application Engine:
1. Select Component Manager node.
2. Click Action > New.
3. Select the region connection point.
4. Set service user name and password.

© Copyright IBM Corporation 2011

Figure 8-18. How to create a new Component Manager F1561.0

Notes:
Help path
• IBM FileNet P8 Information Center > Administering IBM FileNet P8 > Working with
Process Task Manager > Component Manager > Configure Component Manager

8-26 IBM FileNet BPM 5.0: Java API Programming © Copyright IBM Corp. 2011
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
V5.4
Student Notebook

Uempty
Create and configure a Component Manager
Set a connection point for a Component Manager
• Process Task Manager > Application Engine > Component
Managers > [Your Component Manager node]
• General tab
–View connection point name, which is set when the Component
Manager is initially created.
–Set connection point user name and password.
–The Component Manager uses the process connection point to
communicate with the Process Engine.

© Copyright IBM Corporation 2011

Figure 8-19. Set a connection point for a Component Manager F1561.0

Notes:
Help path
• IBM FileNet P8 Information Center > Administering IBM FileNet P8 > Working with
Process Task Manager > Component Manager > Configure Component Manager >
General properties

© Copyright IBM Corp. 2011 Unit 8. Work with Component Integrator 8-27
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
Student Notebook

Create and configure a Component Manager

Set component queues
• Use the Queues parameter in the General tab.
–By default, a Component Manager is connected to all queues in
the selected region when the Component Manager is created.
–Edit the Queues parameter to select only the desired queues for
each Component Manager when you configure multiple
Component Managers.

© Copyright IBM Corporation 2011

Figure 8-20. Set component queues F1561.0

Notes:
Help path
• IBM FileNet P8 Information Center > Administering IBM FileNet P8 > Working with
Process Task Manager > Component Manager > Configure Component Manager >
General properties
The specified connection point must be connected to the region in order for Component
Integration to work.
The screen captures are taken from Process Task Manager. The screen captures show an
example of the General tab and the message box showing the list of component queues
under an isolated region. Originally, the Queues text box in the user interface showed an
asterisk in the field representing all the three available component queues: WSRequest,
CE_Operations, LoanInfoCalculation. These component queues exist in the workflow
database. After the LoanInfoCalculation component queue name is typed into the field, a
single Component Manager is created for that individual component. This result is in
contrast to having a single Component Manager for all three components.

8-28 IBM FileNet BPM 5.0: Java API Programming © Copyright IBM Corp. 2011
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
V5.4
Student Notebook

Uempty
Create and configure a Component Manager
Set Component Manager library paths
• Process Task Manager > Application Engine > Component
Managers > [Your Component Manager node]
• Required Libraries Tab
–Used to add required libraries (Java archive files)
• Libraries for Java component adaptors
–Are custom Java archives deployed to the Application Engine by
solution builder
• Libraries for JMS component adaptors
–Are web application-specific Java archives
–See IBM FileNet P8 help for listing.

© Copyright IBM Corporation 2011

Figure 8-21. Set Component Manager library paths F1561.0

Notes:
Help path
• IBM FileNet P8 Information Center > Administering IBM FileNet P8 > Working with
Process Task Manager > Component Manager > Configure Component Manager >
Required libraries
Use the Required Libraries tab in Process Task Manager on the Application Engine to
specify the location of the .jar files that contain the class associated with each component
queue. Process Task Manager appends the .jar file locations to the classpath when starting
the Component Manager.
You must add a required library entry for each component queue that you create. However,
you do not need to add a library for the FileNet-provided CE_Operations component
queue. The ContentExtendedOps.jar file is made available by default. The
ContentExtendedOps.jar file performs operations using the Content Engine API.
These operations include the following:
• Filing and unfiling a document in a folder

© Copyright IBM Corp. 2011 Unit 8. Work with Component Integrator 8-29
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
Student Notebook

• Getting and setting property values of a document, folder, or custom object

• Publishing
The required JMS libraries for WebLogic, WebSphere, Oracle, and JBoss libraries are
listed in the FileNet P8 help documentation. If you use a third-party web application JMS
solution, see the documentation for that application.

8-30 IBM FileNet BPM 5.0: Java API Programming © Copyright IBM Corp. 2011
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
V5.4
Student Notebook

Uempty
Create and configure a Component Manager
Start and stop components
• Start a Component Manager.
–After a Component Manager starts, component queues are displayed
in the Component Manager node as components.
–Automatic startup option available for a Component Manager.
–Once started, a text message indicating that the component is
waiting for work is displayed.
• Start, stop, and configure individual components.
–A component can be configured to start automatically using the
Process Configuration Console option.
• For each component, you can fine-tune settings at run time in
the Advanced tab.
–Changes affect current instance only.
–Changes persist only until Component Manager is stopped.

© Copyright IBM Corporation 2011

Figure 8-22. Start and stop components F1561.0

Notes:
Help paths
• IBM FileNet P8 Information Center > Administering IBM FileNet P8 > Working with
Process Task Manager > Component Manager > Start and stop Component Manager
• IBM FileNet P8 Information Center > Administering IBM FileNet P8 > Working with
Process Task Manager > Component Manager > Components > Start and Stop
Components
• IBM FileNet P8 Information Center > Administering IBM FileNet P8 > Working with
Process Task Manager > Component Manager > Components > Advanced properties
You can configure components to start automatically using the Process Configuration
Console. These components then start when you start the Component Manager.

© Copyright IBM Corp. 2011 Unit 8. Work with Component Integrator 8-31
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
Student Notebook

Create and configure a Component Manager

Demonstrations
• Create and configure a Component Manager.

© Copyright IBM Corporation 2011

Figure 8-23. Demonstrations F1561.0

Notes:
Demonstration notes:
This demonstration shows you how to create and configure a Component Manager using
Process Task Manager.
The objective is to create a new Component Manager for the CE_Operations queue (a
Java queue) in RegionFive [5]. CE_Operations was previously configured in Process
Configuration Console.
1. In Process Task Manager, select Application Engine > Component Managers node and
click Action > New.
2. In the Select A Connection Point window, select RegionFive from the list and click OK.
3. Notice the name assigned to the new Component Manager: RegionFive.ALL.
4. Click Show queue name next to the Queues field in the General tab. Notice that
automatically all component queues in RegionFive are assigned to the new Component
Manager.

8-32 IBM FileNet BPM 5.0: Java API Programming © Copyright IBM Corp. 2011
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
V5.4
Student Notebook

Uempty 5. Close the message window.

6. Next, change the configuration so that the new Component Manager manages only the
CE_Operations queue.
7. In the Queues field, type CE_Operations and click Apply.
8. Verify that the name of the Component Manager has changed from RegionFive.ALL to
RegionFive.CE_Operations.
9. With the RegionFive.CE_Operations Component Manager selected, click Action >
Start.
10. Wait for the message Component Manager started in the message pane.
11. Verify that the Component Manager starts without any errors.

© Copyright IBM Corp. 2011 Unit 8. Work with Component Integrator 8-33
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
Student Notebook

Create and configure a Component Manager

Activities
In your Student Exercises
• Unit: Work with Component Integrator
• Lesson: Create and configure a Component Manager

• Activities:
–Create and configure a Component Manager.

© Copyright IBM Corporation 2011

Figure 8-24. Activities F1561.0

Notes:
Use your Student Exercises to perform the activities listed.

8-34 IBM FileNet BPM 5.0: Java API Programming © Copyright IBM Corp. 2011
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
V5.4
Student Notebook

Uempty Lesson 8.3. Configure a Java component queue

© Copyright IBM Corp. 2011 Unit 8. Work with Component Integrator 8-35
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
Student Notebook

Lesson:
Configure a Java component queue
• Why is this lesson important to you?
– Your company workflow solution architect has provided a design
specification for a Java component queue. As their programmer, you
write the Java methods for this component (to complete a work item
and to get and set properties to objects on the Content Engine).
These methods will be exposed as operations in a component queue,
and you want to test the code. You are going to deploy the Java
component files, configure a component queue, and test the code.

© Copyright IBM Corporation 2011

Figure 8-25. Lesson: Configure a Java component queue F1561.0

Notes:

8-36 IBM FileNet BPM 5.0: Java API Programming © Copyright IBM Corp. 2011
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
V5.4
Student Notebook

Uempty
Configure a Java component queue
Activities that you need to complete

• Create a Java file for a component.

• Create a Java archive file for deployment as a component.
• Create and configure a Java component queue.

© Copyright IBM Corporation 2011

Figure 8-26. Activities that you need to complete F1561.0

Notes:
These are the activities that you are going to perform in this lesson.

© Copyright IBM Corp. 2011 Unit 8. Work with Component Integrator 8-37
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
Student Notebook

Configure a Java component queue

About Java components
• Java components receive requests from a process region
using component queue operations.
–Each operation is defined as one method in a Java class compiled to
a Java archive file.
–An archive file can have many classes with many methods.
• The Java archive file must be accessible to the Application
Engine.
• The default component, ContentExtendedOps.jar
–Is provided with the system
–Uses parts of the Content Engine API
–Is associated with the CE_Operations component

© Copyright IBM Corporation 2011

Figure 8-27. About Java components F1561.0

Notes:
Help path
• IBM FileNet P8 Information Center > Administering IBM FileNet P8 > Administering
Process Engine > Workflow administration tasks > Configure optional features >
Configure the Component Integrator
The ContentExtendedOps.jar file is associated with the CE_Operations component queue
which is created when an isolated region is initialized.
The ContentExtendedOps.jar file is installed on the Application Engine in Workplace XT at
/opt/IBM/FileNet/WebClient/Router/lib

8-38 IBM FileNet BPM 5.0: Java API Programming © Copyright IBM Corp. 2011
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
V5.4
Student Notebook

Uempty
Configure a Java component queue
Developing Java components
• You must develop a custom Java class and deploy before you
create a Java component queue.
• The Java class must have the following:
–A constructor with no parameters
–Only public methods
–Methods containing only the allowed types of component operation
parameters:
• string, date, integer, float, boolean
• VWAttachment, VWParticipant
• Array of the above types

© Copyright IBM Corporation 2011

Figure 8-28. Developing Java components F1561.0

Notes:
Help path
• IBM FileNet P8 Version 5.0 Information Center > Developing IBM FileNet P8
applications > Process Engine Development > Process Java Developer's Guide >
Developing Process Applications > Developing Work Performers > Developing
Component Integrator-Based Work Performers

© Copyright IBM Corp. 2011 Unit 8. Work with Component Integrator 8-39
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
Student Notebook

Configure a Java component queue

JAAS-based authentication model
• JAAS-based authentication model
–Process Engine authentication
–Component authentication
• Benefits
–Support for heterogeneous security systems
• Requirements for JAAS authentication of components:
–An implementation of the JAAS LoginModule class
–A JAR file containing the custom Java class (component) and the
LoginModule class implementation
–A JAAS login configuration file

© Copyright IBM Corporation 2011

Figure 8-29. JAAS-based authentication model F1561.0

Notes:
Help path
• IBM FileNet P8 Version 5.0 Information Center > Developing IBM FileNet P8
applications > Process Engine Development > Process Java Developer's Guide >
Developing Process Applications > Developing Work Performers > Developing
Component Integrator-Based Work Performers
A JAAS login configuration file contains a section (a LoginContext section) for the
component that specifies the LoginModule class implementation and the associated login
configuration context.

8-40 IBM FileNet BPM 5.0: Java API Programming © Copyright IBM Corp. 2011
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
V5.4
Student Notebook

Uempty
Configure a Java component queue
What is a LoginContext?
• A required Java class that provides authentication
–Required for all Java and JMS components
–Many components can use the same LoginContext
–Also called Configuration Context
• LoginContext
–Defined in JAAS Configuration File
–Specified in Component Manager
• IBM FileNet-provided, default LoginContexts
–CELogin: Authentication to isolated region and object store
–PEWSLogin: Authentication to isolated region
–No action needed to deploy default LoginContexts

© Copyright IBM Corporation 2011

Figure 8-30. What is a LoginContext? F1561.0

Notes:
Help path
• IBM FileNet P8 Version 5.0 Information Center > Developing IBM FileNet P8
applications > Process Engine Development > Process Java Developer's Guide >
Developing Process Applications > Developing Work Performers > Developing
Component Integrator-Based Work Performers
All examples in this course use the IBM FileNet-provided CELogin Configuration Context.

© Copyright IBM Corp. 2011 Unit 8. Work with Component Integrator 8-41
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
Student Notebook

Configure a Java component queue

CELoginModule
• An implementation of the JAAS LoginModule class
• Used by the CE_Operations component
• Defined in JAAS login configuration file
–Name of the file: taskman.login.config
–Installed in <installation directory>/Router on the Application Engine
server
–The LoginContext section in the file is named CELogin
• LoginModule
–One per LoginContext
–Implements the Login method
–Available for IBM FileNet-provided connectors

© Copyright IBM Corporation 2011

Figure 8-31. CELoginModule F1561.0

Notes:
Help path
• IBM FileNet P8 Version 5.0 Information Center > Developing IBM FileNet P8
applications > Process Engine Development > Process Java Developer's Guide >
Developing Process Applications > Developing Work Performers > Developing
Component Integrator-Based Work Performers
The LoginContext section in the file is named CELogin. This section identifies and locates
the program module or modules that are used for logins by the CE_Operations component.

8-42 IBM FileNet BPM 5.0: Java API Programming © Copyright IBM Corp. 2011
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
V5.4
Student Notebook

Uempty
Configure a Java component queue
CELogin context

• Configuration context points to two LoginModules:

–Process Engine LoginModule
–Content Engine LoginModule
• taskman.login.config file
CELogin{
CELogin{
filenet.vw.server.VWLoginModule
filenet.vw.server.VWLoginModule required
required
routerurl="RegionFive";
routerurl="RegionFive";
com.filenet.wcm.toolkit.server.operations.util.CELog
com.filenet.wcm.toolkit.server.operations.util.CELog
inModule
inModule required
required credTag=Clear;
credTag=Clear;
filenet.contentops.ceoperations.util.CELoginModule
filenet.contentops.ceoperations.util.CELoginModule
required
required credTag=Clear;
credTag=Clear;
com.filenet.api.util.WSILoginModule
com.filenet.api.util.WSILoginModule required
required
debug=false;
debug=false;
};
};
© Copyright IBM Corporation 2011

Figure 8-32. CELogin context F1561.0

Notes:

© Copyright IBM Corp. 2011 Unit 8. Work with Component Integrator 8-43
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
Student Notebook

Configure a Java component queue

Steps to create a LoginContext

1. Create a java.security.Principal class.

2. Create a javax.security.auth.spi.LoginModule class.
3. Add your LoginContext to taskman.login.config.
4. Create a JAR file for the principal class and the LoginModule
class.
5. Add the JAR file to the Component Integrator configuration.
6. Configure your component to use the LoginContext.
7. Add the code to your component to retrieve your Principal.

© Copyright IBM Corporation 2011

Figure 8-33. Steps to create a LoginContext F1561.0

Notes:
References
JavaTM Authentication and Authorization Service (JAAS) - LoginModule Developer's
Guide @
http://download.oracle.com/javase/1.4.2/docs/guide/security/jaas/JAASLMDevGuide.html

8-44 IBM FileNet BPM 5.0: Java API Programming © Copyright IBM Corp. 2011
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
V5.4
Student Notebook

Uempty
Configure a Java component queue
Sample code to retrieve VWSession

AccessControlContext
AccessControlContext accessControlContext
accessControlContext ==
AccessController.getContext();
AccessController.getContext();
Subject
Subject sub
sub ==
Subject.getSubject(accessControlContext);
Subject.getSubject(accessControlContext);
Set
Set creds == subject.getPrivateCredentials(
creds subject.getPrivateCredentials(
Class.forName("filenet.vw.api.VWSession"));
Class.forName("filenet.vw.api.VWSession"));
session
session == (VWSession)creds.iterator().next();
(VWSession)creds.iterator().next();
session.some_process_engine_api_call()
session.some_process_engine_api_call()
……

© Copyright IBM Corporation 2011

Figure 8-34. Sample code to retrieve VWSession F1561.0

Notes:

© Copyright IBM Corp. 2011 Unit 8. Work with Component Integrator 8-45
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
Student Notebook

Configure a Java component queue

Sample code to access Content Engine objects
AccessControlContext
AccessControlContext accessControlContext
accessControlContext ==
AccessController.getContext();
AccessController.getContext();
Subject
Subject sub
sub ==
Subject.getSubject(accessControlContext);
Subject.getSubject(accessControlContext);
String
String ceURI
ceURI == filenet.vw.server.Configuration.
filenet.vw.server.Configuration.
GetCEURI(null,
GetCEURI(null, null);
null);
Connection conn
Connection conn = =
Factory.Connection.getConnection(ceURI);
Factory.Connection.getConnection(ceURI);
UserContext
UserContext old
old == UserContext.get();
UserContext.get();
UserContext
UserContext uc = new UserContext();
uc = new UserContext();
uc.pushSubject(subject);
uc.pushSubject(subject);
UserContext.set(uc);
UserContext.set(uc);
EntireNetwork
EntireNetwork entireNetwork
entireNetwork ==
Factory.EntireNetwork.fetchInstance(conn,
Factory.EntireNetwork.fetchInstance(conn, null);
null);
Domain
Domain domain
domain == entireNetwork.get_LocalDomain();
entireNetwork.get_LocalDomain();
String objectStore=vwAttachment.getLibraryName();
String objectStore=vwAttachment.getLibraryName();
……
© Copyright IBM Corporation 2011

Figure 8-35. Sample code to access Content Engine objects F1561.0

Notes:

8-46 IBM FileNet BPM 5.0: Java API Programming © Copyright IBM Corp. 2011
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
V5.4
Student Notebook

Uempty
Configure a Java component queue
Deploying Java Components
• Requirements
–Make Java functionality available to the Java Component Adaptor.
–Give Process Configuration Console access to the Java archive file
on the Application Engine server or workstation.
• To enable component functionality on the Process Engine
–Deploy a copy of the Java archive to the Application Engine.
• This copy of the Java archive is used by the Component Manager
to implement the operations that perform the work.
• To configure the component queue
–Deploy a copy of the Java archive to a work station.
• This local copy is used by Process Configuration Console when
configuring the Java component queue.

© Copyright IBM Corporation 2011

Figure 8-36. Deploying Java Components F1561.0

Notes:
Help path
• IBM FileNet P8 Version 5.0 Information Center > Developing IBM FileNet P8
applications > Process Engine Development > Process Java Developer's Guide >
Developing Process Applications > Developing Work Performers > Developing
Component Integrator-Based Work Performers
If the Component Manager is running, you have to stop and restart it after deploying the
JAR file.

© Copyright IBM Corp. 2011 Unit 8. Work with Component Integrator 8-47
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
Student Notebook

Configure component queues for Java

How to create a Java component queue
• Use Process Configuration Console to create a queue.
1.Right-click the component queue node and click New.
y A wizard steps through Adaptor tab settings.
2.Complete the Adaptor tab options.
y Configure general queue properties, including security.
y Configure JAAS credentials.
y Import component methods as operations.
3.Complete the Operations tab options.
y Expose operations and parameters to Process Designer.
y Rename any parameters as needed.
4.Commit changes.
5.Create a Component Manager in Process Task Manager on the AE
for this component.

© Copyright IBM Corporation 2011

Figure 8-37. How to create a Java component queue F1561.0

Notes:
Help path
• IBM FileNet P8 Information Center > Integrating workflow into document management
> Process Configuration Console > About queues > Manage component queues >
Create a component queue
You configure JAAS for a user with appropriate privileges. The class example uses the
p8admin user. If JAAS security configuration is done in Process Configuration Console, the
user name and password persist when the Component Manager is restarted. If the security
logon is left blank in Process Configuration Console, the component security must be
reentered in the Process Task Manager for the Application Engine every time the process
is restarted.
When using the Process Configuration Console, configure both the Adaptor and
Operations tabs for that component. If the Operations tab is not configured (because the
wizard configures only the Adaptor tab options), the operations will not be exposed in
Process Designer.

8-48 IBM FileNet BPM 5.0: Java API Programming © Copyright IBM Corp. 2011
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
V5.4
Student Notebook

Uempty
Configure a Java component queue
Configure the Java component adaptor
• Component queue Properties > Adaptor tab
–Select adaptor type: Java
–Configure Java adaptor:
• Browse to the JAR file and select the required Java class
• Assign JAAS credentials: user name and password
–Valid domain user who can log on to the Process Engine
–Requires [QP] access to the component queue
• Configuration context
–Name of the LoginContext that manages authentication to the
Process Engine and optional external systems
–Authenticates the JAAS user name
–IBM FileNet-provided: CELogin

© Copyright IBM Corporation 2011

Figure 8-38. Configure the Java component adaptor F1561.0

Notes:
Help paths
• IBM FileNet P8 Information Center > Integrating workflow into document management
> Process Configuration Console > About queues > Manage component queues >
Create a component queue
• IBM FileNet P8 Information Center > Integrating workflow into document management
> Process Configuration Console > About queues > Manage component queues > Java
configuration dialog box
The JAAS user for the component is a valid user on other systems that the component
adaptor connects with, such as Content Engine, databases, and other FileNet P8 systems.
If the component connects to an external system, the JAAS user name and password of
the component must authenticate on that system also.
Example: A Java adaptor uses the CE_Operations queue. The user name and password
of the Java adaptor must authenticate on the object store, because the component queue
is in the same FileNet P8 domain and uses the same LDAP database.

© Copyright IBM Corp. 2011 Unit 8. Work with Component Integrator 8-49
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
Student Notebook

Configure a Java component queue

Import component queue operations
• Component queue Properties > Operations tab
Import operations from Method argument = Read
Java class methods (From work item to adaptor)

Method return type = Write

(From adaptor to work item)

Operation name matches

method name by default Parameter types
(Editable) match method
argument and
Parameter name matches return types
argument name by default
(Editable)

© Copyright IBM Corporation 2011

Figure 8-39. Import component queue operations F1561.0

Notes:
Help path
• IBM FileNet P8 Information Center > Integrating workflow into document management
> Process Configuration Console > About queues > Manage component queues >
Define component queue operations
The diagram shows the Component properties window and the queue operations.
1. Open the Component queue Properties > Operations tab.
2. Click the Import icon in Operations pane.
The “Select Methods to Import” window opens.
3. Select methods from the class exposed in adaptor:
- Selected methods are converted into operations.
- Method name becomes operation name.
- Method parameters become operation parameters.

8-50 IBM FileNet BPM 5.0: Java API Programming © Copyright IBM Corp. 2011
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
V5.4
Student Notebook

Uempty - Parameter names match method argument names (by default).

- Can rename parameters and enter descriptions, if desired.

© Copyright IBM Corp. 2011 Unit 8. Work with Component Integrator 8-51
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
Student Notebook

Configure a Java component queue

Demonstrations
• Create a Java file for a component.
• Create and configure a Java component queue.

© Copyright IBM Corporation 2011

Figure 8-40. Demonstrations F1561.0

Notes:
Demonstration notes - 1
1. Start Eclipse and open the BPMJavaAPISolution project.
2. Review the code in the ComponentEDU.java file.
Note: In the code, the Process Engine session is retrieved from the Component Manager
and this code cannot be run in Eclipse.
The solution contains the ComponentTestEDU.java file with the additional code to create
the Process Engine session.
3. Execute the methods and verify the results as instructed in the “Work with Component
Integrator” unit in the Student Exercises.
Demonstration notes – 2
This demonstration shows you how to create and configure a Java component queue.
1. Log in to Workplace XT as the P8Admin user (password: IBMFileNetP8).

8-52 IBM FileNet BPM 5.0: Java API Programming © Copyright IBM Corp. 2011
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
V5.4
Student Notebook

Uempty 2. Go to the Tools > Administration > Process Configuration Console.

3. Connect to the RegionFive [5] and follow the instructions in procedures 1 and 2 of the
“Create and configure a Java component queue: Walkthrough” activity the “Work with
Component Integrator” unit in the Student Exercises.

© Copyright IBM Corp. 2011 Unit 8. Work with Component Integrator 8-53
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
Student Notebook

Configure a Java component queue

Activities
In your Student Exercises
• Unit: Work with Component Integrator
• Lesson: Configure a Java component queue
• Activities:
–Create a Java file for a component.
–Create a Java archive file for deployment as a component.
–Create and configure a Java component queue.

© Copyright IBM Corporation 2011

Figure 8-41. Activities F1561.0

Notes:
Use your Student Exercises to perform the activities listed.

8-54 IBM FileNet BPM 5.0: Java API Programming © Copyright IBM Corp. 2011
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
V5.4
Student Notebook

Uempty Lesson 8.4. Configure component queues for JMS

© Copyright IBM Corp. 2011 Unit 8. Work with Component Integrator 8-55
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
Student Notebook

Appendix:
Configure component queues for JMS
• Why is this appendix information important to you?
– A workflow uses a component queue to send XML documents
to a JMS queue for printing. The solution architect has provided
the JMS queue specifications. You must create and configure a
component queue to send messages to the JMS queue.

© Copyright IBM Corporation 2011

Figure 8-42. Appendix: Configure component queues for JMS F1561.0

Notes:

8-56 IBM FileNet BPM 5.0: Java API Programming © Copyright IBM Corp. 2011
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
V5.4
Student Notebook

Uempty
Configure component queues for JMS
JMS component adaptor

• JMS adaptor associates a component queue with a JMS

messaging queue and LoginContext

Write Object to JMS Queue

Router
JMS JMS
External Component Component
JMS Adaptor Queue
Queue Login
Auth. Authentication
Context

© Copyright IBM Corporation 2011

Figure 8-43. JMS component adaptor F1561.0

Notes:
Help path
• IBM FileNet P8 Information Center > Developing IBM FileNet P8 applications > Process
Engine Development > Process Java Developer's Guide > Developing Process
Applications > Developing Work Performers > Developing Component Integrator-Based
Work Performers
This diagram illustrates the behavior of the JMS component.
Authentication for the component queue and the external system is handled for both by the
LoginContext. The LoginContext authenticates the user assigned to the component,
permitting the component adaptor to work on the region and any external systems.
JMS
The JMS adaptor places messages on the JMS Queue and dispatches the associated
work item. The JMS adapter handles posting of Process events to a message queue.
The JMS component writes to the external JMS queue only.

© Copyright IBM Corp. 2011 Unit 8. Work with Component Integrator 8-57
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
Student Notebook

The JMS component has only an authentication element. In many cases, the LoginContext
classes that are provided can be used with a JMS component, as long as the JMS security
is properly configured.

8-58 IBM FileNet BPM 5.0: Java API Programming © Copyright IBM Corp. 2011
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
V5.4
Student Notebook

Uempty
Configure component queues for JMS
How to create a JMS component queue
• Use Process Configuration Console to create a new queue.
1. Use the Add a Component Queue wizard.
2. Configure general queue properties, including security.
3. Define JMS component operations.
4. Commit changes to the region.
5. Restart Component Manager.

© Copyright IBM Corporation 2011

Figure 8-44. How to create a JMS component queue F1561.0

Notes:
Help path
• IBM FileNet P8 Information Center > Integrating workflow into document management
> Process Configuration Console > About queues > Manage component queues
You configure JAAS for a user with appropriate privileges. If JAAS security configuration is
done in Process Configuration Console, the user name and password are “sticky,” that is,
they persist when the Component Manager is restarted. If the security logon is left blank in
Process Configuration Console, the component security must be reentered in the AE
Process Task Manager every time the process is

© Copyright IBM Corp. 2011 Unit 8. Work with Component Integrator 8-59
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
Student Notebook

Configure component queues for JMS

Configure general queue properties
• Component queue Properties > Data Fields tab
–Exposed field definition is similar to work and user queues.
• Component queue Properties > Indexes tab
–Index creation is similar to work and user queues.
• Component queue Properties > Security tab
–Security configuration procedure is similar to other queues.
–If security is modified, the JAAS user defined for the component must
be given [QP] access to the queue.
–Restrict access to the following:
• JAAS user
• Connection point user
• Solution builders who transfer workflow definitions
• Process Engine administrators

© Copyright IBM Corporation 2011

Figure 8-45. Configure general queue properties F1561.0

Notes:
Help path
• IBM FileNet P8 Information Center > Integrating workflow into document management
> Process Configuration Console > About queues > Manage component queues >
Specify component properties

8-60 IBM FileNet BPM 5.0: Java API Programming © Copyright IBM Corp. 2011
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
V5.4
Student Notebook

Uempty
Configure component queues for JMS
Configure the JMS component
• Component queue Properties > Adaptor tab
• Select adaptor type: JMS
• Configure Java Adaptor
–Component queue Properties > Adaptor tab
• Configure Operations tab
–Component queue Properties > Operations tab
–Configure the JMS operations.

© Copyright IBM Corporation 2011

Figure 8-46. Configure the JMS component F1561.0

Notes:
Help path
• IBM FileNet P8 Information Center > Integrating workflow into document management
> Process Configuration Console > About queues > Manage component queues > Java
Message Service configuration dialog box

© Copyright IBM Corp. 2011 Unit 8. Work with Component Integrator 8-61
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
Student Notebook

Configure component queues for JMS

Set adaptor properties
• Component queue Properties > Adaptor tab
• Select adaptor type: JMS
• Configure JMS Adaptor
– QueueConnectionFactory (JNDI)
• The name of the JMS object that creates the connection from the component queue
• Depends on web server application type
• Provided by the designer or developer
– Queue Name (JNDI)
• The name of the JMS object that holds the message
• Provided by the designer or developer
• Set Process Engine performance settings:
– Concurrent threads
– Polling rate
– Exception submap
– Startup mode

© Copyright IBM Corporation 2011

Figure 8-47. Set adaptor properties F1561.0

Notes:
Help paths
• IBM FileNet P8 Information Center > Integrating workflow into document management
> Process Configuration Console > About queues > Manage component queues >
Create a component queue
• IBM FileNet P8 Information Center > Integrating workflow into document management
> Process Configuration Console > About queues > Manage component queues > Java
Message Service configuration dialog box
The value for the QueueConnectionFactory depends on the web application server used.
These values are listed in the FileNet P8 help documentation.
The queue name is as defined in JMS. The same name or a different name is used for the
FileNet P8 JMS component queue.

8-62 IBM FileNet BPM 5.0: Java API Programming © Copyright IBM Corp. 2011
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
V5.4
Student Notebook

Uempty
Configure component queues for JMS
Assign JAAS credentials
• Component queue Properties > Adaptor tab
• User name and password
–Valid domain user with log-on access to Process Engine
–Requires [QP] access to the component queue
–Valid user with JMS application authentication
• Configuration context
–Name of the LoginContext that manages authentication to the
Process Engine and optional external systems
–Authenticates the JAAS user name
–FileNet-provided: CELogin
–Developer or designer provides this value.

© Copyright IBM Corporation 2011

Figure 8-48. Assign JAAS credentials F1561.0

Notes:
Help path
• IBM FileNet P8 Information Center > Integrating workflow into document management
> Process Configuration Console > About queues > Manage component queues >
Create a component queue
The same user name and password must authenticate on the web application hosting the
JMS.

© Copyright IBM Corp. 2011 Unit 8. Work with Component Integrator 8-63
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
Student Notebook

Configure component queues for JMS

Define component queue operations
• Component queue Properties > Operations tab
• Click Import button in Operations pane.
–JMS Component Operations Import window opens.
–Enter the name of the operation in the Events pane.
–Add and configure parameters for each operation.
–Operation defintion is similar to work queue operations.
• Edit operation and parameter names.
–Edit them in the Operations tab.
–Do additional configuration in the JMS Component Operations Import
window.

© Copyright IBM Corporation 2011

Figure 8-49. Define component queue operations F1561.0

Notes:
Help path
• IBM FileNet P8 Information Center > Integrating workflow into document management
> Process Configuration Console > About queues > Manage component queues >
Define component queue operations
The operation definition interface looks the same as the interface for Java queues, which
imports external Java methods. Although the Import button looks the same as for the Java
queues, you use this interface to enter the operation name and parameters. You cannot
import methods or operations from JMS.
In the JMS Operations Import window, you enter the operations for the JMS queue. The
events are converted into operations. In the workflow definition, the workflow designer
assigns expressions to these parameters in the component step.

8-64 IBM FileNet BPM 5.0: Java API Programming © Copyright IBM Corp. 2011
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
V5.4
Student Notebook

Uempty
Configure component queues for JMS
Define component queue operations window
• JMS Component queue Properties > Operations tab
• Click Import button in Operations pane.
2. Enter names of
1. Enter name of parameters,
operation parameter types and
optional description

3. Enter optional
operation
description

© Copyright IBM Corporation 2011

Figure 8-50. Define component queue operations window F1561.0

Notes:
The screen capture shows the fields used to define the operations in a JMS component
queue. The labels correspond to the following steps:
1. Enter the name of the operation.
2. Enter names of the parameters, specify the parameter data types, and specify
descriptions if desired.
3. Enter an operation description if desired.

© Copyright IBM Corp. 2011 Unit 8. Work with Component Integrator 8-65
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
Student Notebook

Configure component queues for JMS

Confirm access to JMS queue
• JMS component queues do not require deployed component
files.
• Confirm access information to the JMS message queue
(depends on the application server type):
–JNDI InitialContextFactory
–JMS queue name
• JBoss and WebSphere require additional configuration.
–Configure settings in Process Task Manager.

© Copyright IBM Corporation 2011

Figure 8-51. Confirm access to JMS queue F1561.0

Notes:
Help path
• IBM FileNet P8 Information Center > Developing IBM FileNet P8 applications > Process
Engine Development > Process Java Developer's Guide > Developing Process
Applications > Developing Work Performers > Developing Component Integrator-Base
Work Performers
If a FileNet P8 system uses WebSphere Application Server as the web application server,
some settings in Process Task Manager are necessary for proper JMS operations. The
scope of this course does not include discussion of these site-specific settings for Process
Task Manager.
For information about Process Task Manager settings for WebSphere, go to the Help topic
referenced on this page and click the Configuration for WebSphere and JMS link.

8-66 IBM FileNet BPM 5.0: Java API Programming © Copyright IBM Corp. 2011
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
V5.4
Student Notebook

Uempty Unit 9. Use Roles and Workbaskets

What this unit is about

This unit describes how to write code using Process Engine Java API
to retrieve application spaces, roles, and workbaskets information and
how to query work items from the workbaskets.

What you should be able to do

After completing this unit, you should be able to:
• Retrieve application spaces.
• Retrieve roles.
• Retrieve workbaskets information.
• Retrieve work items from workbaskets.

How you will check your progress

• Successfully complete the activities in the Student Exercises book.

References
www.ibm.com/support/documentation/us/en (Support & downloads
page)
Note: IBM FileNet products belong to the Information Management
product set.

© Copyright IBM Corp. 2011 Unit 9. Use Roles and Workbaskets 9-1
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
Student Notebook

Use Roles and Work Baskets

Unit lessons
This unit contains the following lessons:
• Retrieve application spaces
• Retrieve roles
• Retrieve work baskets
• Query work items from work baskets

© Copyright IBM Corporation 2011

Figure 9-1. Unit lessons F1561.0

Notes:
Lessons in this unit
This unit has four lessons. After the first lesson, each lesson relies on information and skills
taught in the prior lessons. For best results, do these lessons in the sequence presented.
Retrieve application spaces– In this lesson, you write code to retrieve application spaces.
Retrieve roles – In this lesson, you write code to retrieve roles.
Retrieve work baskets– In this lesson, you write code to retrieve work baskets and their
information.
Query work items from work baskets– In this lesson, you write code to query the work
items from work baskets.

9-2 IBM FileNet BPM 5.0: Java API Programming © Copyright IBM Corp. 2011
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
V5.4
Student Notebook

Uempty Lesson 9.1. Retrieve application spaces

© Copyright IBM Corp. 2011 Unit 9. Use Roles and Workbaskets 9-3
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
Student Notebook

Lesson:
Retrieve application spaces
• Why is this lesson important to you?
– Your company manages its business processes using the BPM
application spaces. As their programmer, you are going to write code
to retrieve these application spaces.

© Copyright IBM Corporation 2011

Figure 9-2. Lesson: Retrieve application spaces F1561.0

Notes:

9-4 IBM FileNet BPM 5.0: Java API Programming © Copyright IBM Corp. 2011
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
V5.4
Student Notebook

Uempty
Retrieve application spaces
Activities that you need to complete

• Retrieve application spaces.

© Copyright IBM Corporation 2011

Figure 9-3. Activities that you need to complete F1561.0

Notes:
These are the activities that you are going to perform in this lesson.

© Copyright IBM Corp. 2011 Unit 9. Use Roles and Workbaskets 9-5
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
Student Notebook

Retrieve application spaces

Application spaces

• Provide mechanism to partition roles.

• Contain the resources for custom application or IBM ECM
Widgets.

Claims Human
Human
Claims
Roles
Roles Resources
Resources
Clerk
Clerk Roles
Roles
Adjustor
Adjustor Manager
Manager
Manager
Manager Employee
Employee
In-Baskets
In-Baskets In-Baskets
In-Baskets
Auto
Auto Hiring
Hiring
Home
Home

5
© Copyright IBM Corporation 2011

Figure 9-4. Application spaces F1561.0

Notes:
Help path
• IBM FileNet P8 Version 5.0 Information Center > Integrating workflow into document
management > Process Configuration Console > Manage application spaces > Create
Roles
Roles are defined and managed within the context of an application space.
Application space security settings define the following:
• Who can modify role membership for all roles in the application space.
• Who can modify roles in the application space.
• When multiple application spaces can be created.
• When separate, distinct applications are needed and the user does not need to switch
between roles in the different application spaces.

9-6 IBM FileNet BPM 5.0: Java API Programming © Copyright IBM Corp. 2011
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
V5.4
Student Notebook

Uempty
Retrieve application spaces
Application space and roles
• An application space is used to do the following:
–Logically partition a workflow by business application.
–Assign roles to interact with the application.
• Roles do the following:
–Associate business process users with a mashup page.
• When user logs in, the associated page is displayed.
–Associate user and application space with In-baskets.
• Benefits:
–Workflow environment can be mapped closely to the business
application.
–Users can be focused precisely on the work that they are responsible
for.

© Copyright IBM Corporation 2011

Figure 9-5. Application space and roles F1561.0

Notes:
Help path
• IBM FileNet P8 Version 5.0 Information Center > Integrating workflow into document
management > Process Configuration Console > About application spaces, roles, and
in-baskets
Some workflows are complex, and many people interact with them. An application space is
a mechanism for logically dividing up the workflow according the roles of the different
people who interact with the workflow as it progresses through its steps.
In-baskets are IBM ECM widgets. They have the same purpose as the Inbox in BPM 3.5
and 4.0. They are included in BPM Mashups instead of the Inbox.
Widgets have the following additional capabilities included with the product, which are
more convenient than those available with the Inbox.
• An application space is used to partition a workflow by business application. You can
then assign roles that can operate on them.
• The DefaultApplication tool is provided with the product.

© Copyright IBM Corp. 2011 Unit 9. Use Roles and Workbaskets 9-7
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
Student Notebook

Retrieve application spaces

Create an application space

© Copyright IBM Corporation 2011

Figure 9-6. Create an application space F1561.0

Notes:
Help path
• IBM FileNet P8 Version 5.0 Information Center > Integrating workflow into document
management > Process Configuration Console > Manage application spaces > Create
an application space
This diagram shows creating an application space.
To create a new application space (Use Process Configuration Console)
1. If the application space window is not open, select the application spaces node in the
Configuration Console tree, and then click New on the toolbar.
2. Enter a name for application space.
3. In the Description box, you can optionally enter a brief description to document the
purpose of the application space, or to list any special notes.
4. Click Create.

9-8 IBM FileNet BPM 5.0: Java API Programming © Copyright IBM Corp. 2011
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
V5.4
Student Notebook

Uempty 5. Select the new application space and click Properties on the toolbar to define security
and roles for the application. See application space Properties for instructions.
6. Click OK when done.
7. Click Commit Changes on the toolbar to apply this change to your isolated region.

© Copyright IBM Corp. 2011 Unit 9. Use Roles and Workbaskets 9-9
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
Student Notebook

Retrieve application spaces

Configure roles for an application space

© Copyright IBM Corporation 2011

Figure 9-7. Configure roles for an application space F1561.0

Notes:
The screen capture shows the configuration of the roles for an application space.
Help path
• IBM FileNet P8 Version 5.0 Information Center > Integrating workflow into document
management > Process Configuration Console > Manage application spaces > Create
roles

9-10 IBM FileNet BPM 5.0: Java API Programming © Copyright IBM Corp. 2011
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
V5.4
Student Notebook

Uempty
Retrieve application spaces
Steps to retrieve application spaces

1. Log on to the Process Engine.

vwSession
vwSession == new
new VWSession(…)
VWSession(…)

2. Get system configuration.

vwSession.fetchSystemConfiguration()
vwSession.fetchSystemConfiguration()

3. Get application spaces and their names.

vwSystemConfiguration.getApplicationSpaceDefini
vwSystemConfiguration.getApplicationSpaceDefini
tions();
tions();
VWApplicationSpaceDefinition.. getName
VWApplicationSpaceDefinition getName()()

© Copyright IBM Corporation 2011

Figure 9-8. Steps to retrieve application spaces F1561.0

Notes:

© Copyright IBM Corp. 2011 Unit 9. Use Roles and Workbaskets 9-11
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
Student Notebook

Retrieve application spaces

vwSession.fetchSystemConfiguration()

public
public VWSystemConfiguration
VWSystemConfiguration
fetchSystemConfiguration()
fetchSystemConfiguration()
• Parameters
–Nothing
• Returns
–VWSystemConfiguration object that contains the configuration
information for the isolated region

© Copyright IBM Corporation 2011

Figure 9-9. vwSession.fetchSystemConfiguration() F1561.0

Notes:
Configuration includes information about application spaces, queues, rosters, and logs.

9-12 IBM FileNet BPM 5.0: Java API Programming © Copyright IBM Corp. 2011
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
V5.4
Student Notebook

Uempty
Retrieve application spaces
vwSystemConfiguration.getApplicationSpaceDefinitions()

public
public VWApplicationSpaceDefinition[]
VWApplicationSpaceDefinition[]
getApplicationSpaceDefinitions()
getApplicationSpaceDefinitions()
• Parameters
–Nothing
• Returns
– An array of application space definitions associated with this system
configuration

© Copyright IBM Corporation 2011

Figure 9-10. vwSystemConfiguration.getApplicationSpaceDefinitions() F1561.0

Notes:

© Copyright IBM Corp. 2011 Unit 9. Use Roles and Workbaskets 9-13
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
Student Notebook

Retrieve application spaces

vwApplicationSpaceDefinition.getName()

public
public java.lang.String
java.lang.String getName()
getName()

• Parameters
–Nothing
• Returns
– A String containing the current name of the application space

© Copyright IBM Corporation 2011

Figure 9-11. vwApplicationSpaceDefinition.getName() F1561.0

Notes:

9-14 IBM FileNet BPM 5.0: Java API Programming © Copyright IBM Corp. 2011
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
V5.4
Student Notebook

Uempty
Retrieve application spaces
Sample code to get application spaces

myPESession
myPESession == new
new VWSession
VWSession
(userName,password,connectionPoint);
(userName,password,connectionPoint);
VWSystemConfiguration
VWSystemConfiguration config
config ==
session.fetchSystemConfiguration();
session.fetchSystemConfiguration();
VWApplicationSpaceDefinition
VWApplicationSpaceDefinition appSpaces[]
appSpaces[] ==
config.getApplicationSpaceDefinitions();
config.getApplicationSpaceDefinitions();
for
for (int
(int i=0;i<
i=0;i< appSpaces.length;
appSpaces.length; i++){
i++){
System.out.println("Application
System.out.println("Application space:"
space:"
++ appSpaces[i].getName());
appSpaces[i].getName());
}}

© Copyright IBM Corporation 2011

Figure 9-12. Sample code to get application spaces F1561.0

Notes:

© Copyright IBM Corp. 2011 Unit 9. Use Roles and Workbaskets 9-15
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
Student Notebook

Retrieve application spaces

Demonstrations
• Retrieve application spaces.
–Explore the code sample.
–Run the solution code.
–Observe the results.

© Copyright IBM Corporation 2011

Figure 9-13. Demonstrations F1561.0

Notes:
Demonstration notes
1. Start Eclipse and open the BPMJavaAPISolution project.
2. Review the code for retrieve application spaces in the getApplicationSpacesEDU(…)
method in the InbasketsEDU.java file.
3. Run the code and verify the results as instructed in the “Use Roles and Work Baskets”
unit in the Student Exercises.

9-16 IBM FileNet BPM 5.0: Java API Programming © Copyright IBM Corp. 2011
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
V5.4
Student Notebook

Uempty
Retrieve application spaces
Activities
In your Student Exercises
• Unit: Use Roles and Work Baskets
• Lesson: Retrieve application spaces
• Activities:
– Retrieve application spaces.

© Copyright IBM Corporation 2011

Figure 9-14. Activities F1561.0

Notes:
Use your Student Exercises to perform the activities listed.

© Copyright IBM Corp. 2011 Unit 9. Use Roles and Workbaskets 9-17
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
Student Notebook

9-18 IBM FileNet BPM 5.0: Java API Programming © Copyright IBM Corp. 2011
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
V5.4
Student Notebook

Uempty Lesson 9.2. Retrieve roles

© Copyright IBM Corp. 2011 Unit 9. Use Roles and Workbaskets 9-19
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
Student Notebook

Lesson:
Retrieve roles
• Why is this lesson important to you?
– Your company uses roles to organize work. As their programmer,
you are going to write code to retrieve these roles.

© Copyright IBM Corporation 2011

Figure 9-15. Lesson: Retrieve roles F1561.0

Notes:
Roles specify which users can access specific types of workflows. For each role, you
specify the Web address of the ECM Widgets home page for that role, the users who are
members of the role, and the in-baskets that are accessible for the role.

9-20 IBM FileNet BPM 5.0: Java API Programming © Copyright IBM Corp. 2011
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
V5.4
Student Notebook

Uempty
Retrieve roles
Activities that you need to complete

• Retrieve roles.

© Copyright IBM Corporation 2011

Figure 9-16. Activities that you need to complete F1561.0

Notes:
These are the activities that you are going to perform in this lesson.

© Copyright IBM Corp. 2011 Unit 9. Use Roles and Workbaskets 9-21
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
Student Notebook

Retrieve roles
Roles, in-baskets, filters, and queues relationship
Role In-basket Filter Queue

Supervisor Supervisor
Priority > 5
In-basket Queue

Processor
Supervisor Amount > 5000
Supervisor
In-basket Processor
Queue
Processor
Processor Amount <= 5000
In-basket

Customer Customer
Customer No filter
In-basket Queue

© Copyright IBM Corporation 2011

Figure 9-17. Roles, in-baskets, filters, and queues relationship F1561.0

Notes:
In the diagram, the Supervisor role is associated with two in-baskets:
• Processor Supervisor in-basket
• Supervisor in-basket
The Processor and Customer roles are associated with one in-basket.
Both the Processor Supervisor and the Processor in-baskets get the work items from
Processor queue. However, the Processor in-basket returns only work items with amounts
less than or equal to 5000 (Amount <= 5000), while the Processor Supervisor in-basket
returns work items with amounts greater than 5000 (Amount > 5000), according to the
associated filters.

9-22 IBM FileNet BPM 5.0: Java API Programming © Copyright IBM Corp. 2011
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
V5.4
Student Notebook

Uempty
Retrieve roles
Creating roles at design time
• Create roles from
–Process Designer
–Configuration Console
• Assign LDAP users
and groups to roles.
• Specify home page.
• Associate with in-
baskets.

© Copyright IBM Corporation 2011

Figure 9-18. Creating roles at design time F1561.0

Notes:
The screen capture shows the configuration of the roles for an application space.
Help path
• IBM FileNet P8 Version 5.0 Information Center > Integrating workflow into document
management > Process Configuration Console > Manage application spaces > Create
roles
To define a new role:
1. Click Add on the Roles bar. Double-click the new entry and replace the default name,
NewRole1, with a new name. Some users are assigned to more than one role, so the
name needs to provide some clue of the type of work.
2. Optionally enter a description for this role.
3. Enter a Web address of the home page of this role where the user selects an in-basket
with work items. If you know the Web address, you can enter it and select Preview to
view the home page.

© Copyright IBM Corp. 2011 Unit 9. Use Roles and Workbaskets 9-23
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
Student Notebook

4. Select one or more in-baskets that are available for this role. If the in-basket does not
exist, click the Create in-basket button to create a new in-basket.
5. To assign members for this role, click Modify and select the users or groups to be
members of this role. These users are able to select this role and open the in-baskets to
process the work items.
6. Click Commit Changes on the Action bar of the Configuration tab if you are in Process
Designer to save your configuration change.

9-24 IBM FileNet BPM 5.0: Java API Programming © Copyright IBM Corp. 2011
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
V5.4
Student Notebook

Uempty
Retrieve roles
How roles work at run time
• User logs in and specifies a role.
• Custom application displays page assigned to the role.
• Custom page shows a list of in-baskets associated with the
role.
• User operates on these in-baskets.

© Copyright IBM Corporation 2011

Figure 9-19. How roles work at run time F1561.0

Notes:
Roles determine almost all aspects of what is presented in the user interface, including its
layout appearance and what data and functionality are available to the current user.

© Copyright IBM Corp. 2011 Unit 9. Use Roles and Workbaskets 9-25
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
Student Notebook

Retrieve roles
Assign LDAP users and groups

© Copyright IBM Corporation 2011

Figure 9-20. Assign LDAP users and groups F1561.0

Notes:
The screen capture shows the assignment of LDAP users and groups to the roles in an
application space.

9-26 IBM FileNet BPM 5.0: Java API Programming © Copyright IBM Corp. 2011
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
V5.4
Student Notebook

Uempty
Retrieve roles
Associate role with in-baskets

© Copyright IBM Corporation 2011

Figure 9-21. Associate role with in-baskets F1561.0

Notes:
The screen captures shows the association of a role with an in-basket.

© Copyright IBM Corp. 2011 Unit 9. Use Roles and Workbaskets 9-27
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
Student Notebook

Retrieve roles
VWRole object
• Represents a role in an application space
• Associated with one or more work baskets

© Copyright IBM Corporation 2011

Figure 9-22. VWRole object F1561.0

Notes:
Users are assigned roles. A role defines which different types of activities the user sees,
and what kind of work the user processes. Roles might vary according to job types and
tasks. For example, one user might be assigned a Clerk role and perform one set of basic
tasks, while another user is assigned the role of Approver, and performs a different set of
tasks.
You define roles such as Clerk, Approver, and so on, to organize work. To make it easy for
users to select work, you define in-baskets, which contain work items. A workflow
administrator creates roles and in-baskets using Process Designer.
When a role is created, an administrator assigns LDAP users and groups to the role and
associates one or more in-baskets with the role. A business analyst can create a business
space, and then create a page that includes an In-basket widget. Or the business analyst
can use one of the predefined templates. The next step is to configure the in-basket to use
a role. The business analyst also configures the business space so that the same LDAP
groups that are assigned to the role are also given rights to view the business space. When

9-28 IBM FileNet BPM 5.0: Java API Programming © Copyright IBM Corp. 2011
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
V5.4
Student Notebook

Uempty a BPM user logs into Business Space and opens the business space, the In-basket widget
displays all of the in-baskets associated with that user role.
If necessary, roles can be partitioned into application spaces, a mechanism for managing
security for roles. A default application space is configured on the Process Engine server
and in IBM ECM Widgets. A workflow administrator can create additional application
spaces to separate role management tasks.

© Copyright IBM Corp. 2011 Unit 9. Use Roles and Workbaskets 9-29
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
Student Notebook

Retrieve roles
Steps to retrieve all roles in an application space

1. Get a VWApplicationSpaceDefinition object.

2. Get all the roles in the application space.
vwApplicationSpaceDefinition.
vwApplicationSpaceDefinition.
getRoleDefinitions()
getRoleDefinitions()

3. Iterate through the role collection

for
for (int
(int ii == 0;
0; ii << roles.length;
roles.length;
i++)
i++) {{
System.out.println(“Role
System.out.println(“Role Authored
Authored Name:"
Name:"
++ roles[i].getAuthoredName());
roles[i].getAuthoredName());
}}

© Copyright IBM Corporation 2011

Figure 9-23. Steps to retrieve all roles in an application space F1561.0

Notes:

9-30 IBM FileNet BPM 5.0: Java API Programming © Copyright IBM Corp. 2011
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
V5.4
Student Notebook

Uempty
Retrieve roles
Steps to retrieve roles for a given user

1. Get a session object.

VWSession(user,
VWSession(user, password,
password, connectionPoint)
connectionPoint)

2. Get the roles associated with the logged in user.

vwSession.fetchMyRoles(…)
vwSession.fetchMyRoles(…)

3. Iterate through the collection.

for
for (int
(int ii == 0;
0; ii << roles.length;
roles.length;
i++)
i++) {{
System.out.println(“Role
System.out.println(“Role Authored
Authored Name:"
Name:" ++
roles[i].getAuthoredName());
roles[i].getAuthoredName());
……
}}
© Copyright IBM Corporation 2011

Figure 9-24. Steps to retrieve roles for a given user F1561.0

Notes:

© Copyright IBM Corp. 2011 Unit 9. Use Roles and Workbaskets 9-31
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
Student Notebook

Retrieve roles
vwApplicationSpaceDefinition.getRoleDefinitions()

public
public VWRoleDefinition[]
VWRoleDefinition[] getRoleDefinitions()
getRoleDefinitions()

• Parameters
–None
• Returns
–An array of VWRoleDefinition objects
• Note
– This method returns null if no role definitions are found.

© Copyright IBM Corporation 2011

Figure 9-25. vwApplicationSpaceDefinition.getRoleDefinitions() F1561.0

Notes:

9-32 IBM FileNet BPM 5.0: Java API Programming © Copyright IBM Corp. 2011
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
V5.4
Student Notebook

Uempty
Retrieve roles
vwApplicationSpaceDefinition.getRoleDefinition()

public
public VWRoleDefinition
VWRoleDefinition
getRoleDefinition(String
getRoleDefinition(String roleName)
roleName)

• Parameters
–roleName – Specify a String containing the name of a role.
• Returns
–A VWRoleDefinition identified by the specified name
• Note
– This method returns null if the role definition is not found.

© Copyright IBM Corporation 2011

Figure 9-26. vwApplicationSpaceDefinition.getRoleDefinition() F1561.0

Notes:

© Copyright IBM Corp. 2011 Unit 9. Use Roles and Workbaskets 9-33
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
Student Notebook

Retrieve roles
vwSesssion.fetchMyRoles(…)

public
public VWRole[]
VWRole[] fetchMyRoles(String
fetchMyRoles(String
appSpaceName)
appSpaceName)

• Parameters
–appSpaceName – Specify a String containing the name of an
application space in which the roles are defined.
• Returns
–An array of VWRole objects representing the current user roles in
the specified application space
• Note
– If appSpaceName is null, all application spaces are used.

© Copyright IBM Corporation 2011

Figure 9-27. vwSesssion.fetchMyRoles(...) F1561.0

Notes:
Retrieve all roles that the user is associated with in an application space.
Example use: Retrieve all roles for a user when he logs in to a mashup application. The
user can then choose a role to use in the application.

9-34 IBM FileNet BPM 5.0: Java API Programming © Copyright IBM Corp. 2011
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
V5.4
Student Notebook

Uempty
Retrieve roles
vwSesssion.fetchMyRole(…)

public
public VWRole
VWRole fetchMyRole(
fetchMyRole(
String
String roleName,
roleName,
String
String appSpaceName)
appSpaceName)

• Parameters
–roleName – Specify a String containing the name of the role.
–appSpaceName – Specify a String containing the name of an
application space in which the roles are defined.
• Returns
–VWRole object representing the current user role in the specified
application space

© Copyright IBM Corporation 2011

Figure 9-28. vwSesssion.fetchMyRole(...) F1561.0

Notes:
Retrieve role object for a specific role and application space.
Example use: Retrieve the role object and use the role object to retrieve the in-baskets
that are associated with that role.

© Copyright IBM Corp. 2011 Unit 9. Use Roles and Workbaskets 9-35
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
Student Notebook

Retrieve roles
vwRole.getName()

public
public String
String getName()
getName()

• Parameters
–None
• Returns
–A String containing the current name of the role

© Copyright IBM Corporation 2011

Figure 9-29. vwRole.getName() F1561.0

Notes:

9-36 IBM FileNet BPM 5.0: Java API Programming © Copyright IBM Corp. 2011
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
V5.4
Student Notebook

Uempty
Retrieve roles
vwRole.getAuthoredName()

public
public String
String getAuthoredName()
getAuthoredName()

• Parameters
–None
• Returns
– A String containing the name originally assigned to the role

© Copyright IBM Corporation 2011

Figure 9-30. vwRole.getAuthoredName() F1561.0

Notes:

© Copyright IBM Corp. 2011 Unit 9. Use Roles and Workbaskets 9-37
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
Student Notebook

Retrieve roles
Sample code to retrieve all roles in an application space

VWRoleDefinition
VWRoleDefinition roles[]
roles[] ==
appSpace.getRoleDefinitions();
appSpace.getRoleDefinitions();
if
if (roles
(roles !=!= null){
null){
System.out.println("
System.out.println(" ListList of
of all
all roles
roles
in the application space:
in the application space: " );" );
for(int
for(int ii == 0;
0; ii << roles.length;
roles.length; i++){
i++){
System.out.println("Role
System.out.println("Role Name:"
Name:" ++
roles[i].getName());
roles[i].getName());
System.out.println("AuthoredName:"
System.out.println("AuthoredName:" ++
roles[i].getAuthoredName());
roles[i].getAuthoredName());
}}

© Copyright IBM Corporation 2011

Figure 9-31. Sample code to retrieve all roles in an application space F1561.0

Notes:
The sample code in this page assumes that a VWApplicationSpaceDefinition object is
already retrieved and assigned to a variable called appSpace.

9-38 IBM FileNet BPM 5.0: Java API Programming © Copyright IBM Corp. 2011
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
V5.4
Student Notebook

Uempty
Retrieve roles
Sample code to retrieve roles for a given user

VWRole
VWRole roles[]
roles[] ==
myPESession.fetchMyRoles(appSpaceName);
myPESession.fetchMyRoles(appSpaceName);
if
if (roles
(roles ==== null
null || || roles.length
roles.length << 1)1)
System.out.println("No
System.out.println("No role assgiged to
role assgiged to this
this
logon user "
logon user " + +
myPESession.fetchCurrentUserInfo().getName());
myPESession.fetchCurrentUserInfo().getName());
else{
else{
System.out.println("List
System.out.println("List of of roles
roles available
available inin
the application space - " + appSpaceName);
the application space - " + appSpaceName);
for(int
for(int ii == 0;
0; ii << roles.length;
roles.length; i++)
i++) {{
System.out.println("Role
System.out.println("Role Name:" Name:" ++
roles[i].getName());
roles[i].getName());
System.out.println("Role
System.out.println("Role authoredName:"+
authoredName:"+
roles[i].getAuthoredName());
roles[i].getAuthoredName());
}}

© Copyright IBM Corporation 2011

Figure 9-32. Sample code to retrieve roles for a given user F1561.0

Notes:
The sample code in this page assumes that a VWSession is already established and
assigned to a variable called myPESession.

© Copyright IBM Corp. 2011 Unit 9. Use Roles and Workbaskets 9-39
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
Student Notebook

Retrieve roles
Demonstrations
• Retrieve all roles in an application space.
• Retrieve roles for a given user.
–Explore the code sample.
–Run the solution code.
–Observe the results.

© Copyright IBM Corporation 2011

Figure 9-33. Demonstrations F1561.0

Notes:
Demonstration notes
1. Start Eclipse and open the BPMJavaAPISolution project.
2. Review the code for retrieving all the roles in a given application space in the
getAllRolesEDU(…) method of the InbasketsEDU.java file.
3. This method is called inside the getApplicationSpacesEDU(…) method.
4. Run the code and verify the results as instructed in the “Use Roles and Work Baskets”
unit in the Student Exercises.
5. Repeat steps 2 and 4 for the getRolesforUserEDU(…) method of the
InbasketsEDU.java file for retrieving the roles for a given user.
6. This method is called inside the main(…) method.

9-40 IBM FileNet BPM 5.0: Java API Programming © Copyright IBM Corp. 2011
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
V5.4
Student Notebook

Uempty
Retrieve roles
Activities
In your Student Exercises
• Unit: Use Roles and Work Baskets
• Lesson: Retrieve roles
• Activities:
–Retrieve roles.

© Copyright IBM Corporation 2011

Figure 9-34. Activities F1561.0

Notes:
Use your Student Exercises to perform the activities listed.

© Copyright IBM Corp. 2011 Unit 9. Use Roles and Workbaskets 9-41
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
Student Notebook

9-42 IBM FileNet BPM 5.0: Java API Programming © Copyright IBM Corp. 2011
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
V5.4
Student Notebook

Uempty Lesson 9.3. Retrieve work baskets

© Copyright IBM Corp. 2011 Unit 9. Use Roles and Workbaskets 9-43
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
Student Notebook

Lesson:
Retrieve work baskets
• Why is this lesson important to you?
– Your company uses work baskets to filter work items based on roles
to organize work. As their programmer, you are going to write code
to retrieve these work baskets.

© Copyright IBM Corporation 2011

Figure 9-35. Lesson: Retrieve work baskets F1561.0

Notes:

9-44 IBM FileNet BPM 5.0: Java API Programming © Copyright IBM Corp. 2011
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
V5.4
Student Notebook

Uempty
Retrieve work baskets
Activities that you need to complete

• Retrieve work baskets for a given role.

• Retrieve work baskets from a queue.
• Retrieve work basket information.

© Copyright IBM Corporation 2011

Figure 9-36. Activities that you need to complete F1561.0

Notes:
These are the activities that you are going to perform in this lesson.

© Copyright IBM Corp. 2011 Unit 9. Use Roles and Workbaskets 9-45
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
Student Notebook

Retrieve work baskets

VWWorkbasket object
• A work basket
– Is also known as in-basket
–Filters the work items based on query specification defined in
Process Engine.
• Work basket definition includes
–Columns to decide which workflow fields are displayed.
–Custom filters that filter the work items at run time.

© Copyright IBM Corporation 2011

Figure 9-37. VWWorkbasket object F1561.0

Notes:
You create in-baskets to provide a list of work items in a queue that are to be processed by
users who are members of a certain role.
You can define multiple in-baskets for the same queue and have each in-basket show
different items, as specified by a predefined query. This is done by assigning specific roles
to process each in-basket. Each user (role member) sees only the types of work
appropriate for the role they are performing.

9-46 IBM FileNet BPM 5.0: Java API Programming © Copyright IBM Corp. 2011
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
V5.4
Student Notebook

Uempty
Retrieve work baskets
In-baskets

• Provide ability to selectively retrieve work items from

queue for processing.
• At design time
–Select columns to be displayed.
–Specify runtime filter. (Values are specified at runtime.)
–Specify predefined content filter (not customizable at runtime).

© Copyright IBM Corporation 2011

Figure 9-38. In-baskets F1561.0

Notes:
An in-basket can be used to find and process work items in the context of workflow.
In-baskets provide a filtered access to workflow queues based on the user role. A workflow
queue, step, and security profile are always needed to configure an in-basket . You can
have as many in-basket definitions for the combinations of work queues and roles.
In-baskets are defined by the following:
• Filtered view of workflow queue contents
Queue filters – These configured filters determine what the user can see in the queue.
Inbasket filters – These configurable options are selected by the user to further limit the
in-basket list.
Sort order – Sort order prioritizes work delivery for users and can be based on a single
field, a combination of fields, or a complex SQL custom function.
User column sorting is configurable; each column supports complex sorting criteria.
At run time, you can use in-baskets to do the following:

© Copyright IBM Corp. 2011 Unit 9. Use Roles and Workbaskets 9-47
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
Student Notebook

• Specify values for the dynamic query criteria.

• Sort the results based on one of the display columns.
• Specify page size.
• Create predictable queue queries.
• Leverage local database administrator experts to create optimal database indices.
• Leverage the database for optimizing the query.

9-48 IBM FileNet BPM 5.0: Java API Programming © Copyright IBM Corp. 2011
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
V5.4
Student Notebook

Uempty
Retrieve work baskets
In-basket widget
• BPM mashups includes a widget called the In-basket.
–It serves the same purpose as the Inbox in Workplace.
• In-basket provides ability to help the user filter and sort work
items
–Selectively retrieve work items from queue for processing.
– Focus on the work items based on priorities.

© Copyright IBM Corporation 2011

Figure 9-39. In-basket widget F1561.0

Notes:
The IBM ECM Widget In-basket is analogous to the Inbox. Work is retrieved from a queue
and presented to the user through the In-basket. The In-basket is an IBM ECM Widget,
which the designer embeds in BPM mashup pages. The In-basket has more capabilities for
the user than the Inbox. Most importantly, the user can use the In-basket to dynamically
filter work retrieved from the queue.

© Copyright IBM Corp. 2011 Unit 9. Use Roles and Workbaskets 9-49
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
Student Notebook

Retrieve work baskets

In-baskets tab in Process Designer

© Copyright IBM Corporation 2011

Figure 9-40. In-baskets tab in Process Designer F1561.0

Notes:
The screen capture shows the In-baskets tab from Process Designer.

9-50 IBM FileNet BPM 5.0: Java API Programming © Copyright IBM Corp. 2011
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
V5.4
Student Notebook

Uempty
Retrieve work baskets
Specify reference to work queue

© Copyright IBM Corporation 2011

Figure 9-41. Specify reference to work queue F1561.0

Notes:
The screen capture shows the assignment of a work queue to an in-basket.
An in-basket references a work queue, that is, it is a view of a work queue.

© Copyright IBM Corp. 2011 Unit 9. Use Roles and Workbaskets 9-51
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
Student Notebook

Retrieve work baskets

In-basket component: displayable columns

• Specify fields that are

displayed when listing the
results of an in-basket query.
• Any field exposed to the
queue can be displayed.
• Can configure the order for
displaying the columns.
• Can specify columns that are
sortable at runtime.

© Copyright IBM Corporation 2011

Figure 9-42. In-basket component: displayable columns F1561.0

Notes:
The screen capture shows the configuration for displaying the columns.

9-52 IBM FileNet BPM 5.0: Java API Programming © Copyright IBM Corp. 2011
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
V5.4
Student Notebook

Uempty
Retrieve work baskets
In-basket component: runtime filters

• Set of criteria that the user

sets at run-time to filter the
contents.
• Possible operators: <, <=, >,
>=, like, not like, and
• For example: Zip Code = Value1
and Mortgage Value >= Value2.

© Copyright IBM Corporation 2011

Figure 9-43. In-basket component: runtime filters F1561.0

Notes:
The screen capture shows the configuration for runtime filters.
The Inbasket Filters displays the data entry fields at run time configured for each in-basket.
These filters are used to further limit the contents of the selected in-basket. After a filter has
been entered in these data fields, the in-basket must be selected again in order to cause
the Browse List contents to be refreshed. The number of data entry fields, their type, and
size are based on the in-basket filters defined in the In-basket Configuration.

© Copyright IBM Corp. 2011 Unit 9. Use Roles and Workbaskets 9-53
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
Student Notebook

Retrieve work baskets

In-basket component: content filter

• Set of hardcoded criteria to

limit the content of the in-
basket.
• Possible operators: <, <=, >,
>=, like, not like, (, ), or, and
• For example: Mortgage Value
>= 500000.00 and (Zip Code =
92626 or Zip Code = 92625).

© Copyright IBM Corporation 2011

Figure 9-44. In-basket component: content filter F1561.0

Notes:
The screen capture shows the configuration for content filters.

9-54 IBM FileNet BPM 5.0: Java API Programming © Copyright IBM Corp. 2011
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
V5.4
Student Notebook

Uempty
Retrieve work baskets
Steps to retrieve work baskets for a role
1. Create a Process Engine session object.
vwSession()
vwSession()
1. Retrieve roles.
vwSession.fetchMyRoles(…)
vwSession.fetchMyRoles(…)
1. Retrieve work baskets associated with role.
vwRole.getWorkBasketReferences()
vwRole.getWorkBasketReferences()

4. Get the work basket name and name of the queue it represents.
workBasketReference.getWorkBasketName()
workBasketReference.getWorkBasketName()
workBasketReference.getWorkBasketAuthored
workBasketReference.getWorkBasketAuthored
Name()
Name()
workBasketReference.getQueueName()
workBasketReference.getQueueName()
© Copyright IBM Corporation 2011

Figure 9-45. Steps to retrieve work baskets for a role F1561.0

Notes:
Use the following steps to retrieve work baskets from a queue:
1. Create a Process Engine session object.
2. Retrieve the queue from the session object: vwSession.getQueue(…)
3. Retrieve the work baskets from the queue: vwQueue.fetchWorkBaskets()
4. Retrieve the work basket name: vwWorkBasket.getName()

© Copyright IBM Corp. 2011 Unit 9. Use Roles and Workbaskets 9-55
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
Student Notebook

Retrieve work baskets

vwRole.getWorkBasketReferences()

public
public VWRole.WorkBasketReference[]
VWRole.WorkBasketReference[]
getWorkBasketReferences()
getWorkBasketReferences()
• Parameters
–None
• Returns
–An array of WorkBasketReference objects identifying the work
baskets associated with this role

• Notes
–Use WorkBasketReference to retrieve information about a work
baskets associated with a role.

© Copyright IBM Corporation 2011

Figure 9-46. vwRole.getWorkBasketReferences() F1561.0

Notes:
You can also retrieve work baskets from a role using this method:
vwRole.fetchWorkBaskets()
public VWWorkBasket[] fetchWorkBaskets()
Parameters: None
Returns: An array of VWWorkBasket objects that this role references

9-56 IBM FileNet BPM 5.0: Java API Programming © Copyright IBM Corp. 2011
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
V5.4
Student Notebook

Uempty
Retrieve work baskets
vwQueue.fetchWorkBaskets()

public
public VWWorkBasket[]
VWWorkBasket[] fetchWorkBaskets()
fetchWorkBaskets()

• Parameters
–None
• Returns
–An array of work basket objects associated with this queue

© Copyright IBM Corporation 2011

Figure 9-47. vwQueue.fetchWorkBaskets() F1561.0

Notes:
You can retrieve a specified work basket from a queue using the
vwQueue.fetchWorkBasket (…) method:
public VWWorkBasket fetchWorkBasket(String workbasketName)
Parameter: A String containing the name of a work basket in this queue
Returns: The specified work basket associated with this queue
You can retrieve a specified work basket from a role using the vwQueue.fetchWorkBasket
(…) method:
public VWWorkBasket fetchWorkBasket(String queueName,String workbasketName)
You need to provide the name of the queue that the work basket belongs to.
Parameters:
A String containing the queue name
A String containing the name of a work basket to retrieve
Returns: The specified work basket associated with this role

© Copyright IBM Corp. 2011 Unit 9. Use Roles and Workbaskets 9-57
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
Student Notebook

Retrieve work baskets

Sample code to retrieve work baskets from a role

VWRole.WorkBasketReference
VWRole.WorkBasketReference wbs[]
wbs[] ==
vwRole.getWorkBasketReferences();
vwRole.getWorkBasketReferences();
if(wbs
if(wbs !=
!= null)
null)
{{
for(int
for(int ii == 0;
0; ii << wbs.length;
wbs.length; i++)
i++)
{{
System.out.println("Workbasket
System.out.println("Workbasket name:"
name:"
++ wbs[i].getWorkBasketName());
wbs[i].getWorkBasketName());
System.out.println("Queue
System.out.println("Queue name:"
name:" ++
wbs[i].getQueueName());
wbs[i].getQueueName());
}}
}}

© Copyright IBM Corporation 2011

Figure 9-48. Sample code to retrieve work baskets from a role F1561.0

Notes:
The sample code in this page assumes that the VWRole type variable called vwRole has
already been assigned a valid value.

9-58 IBM FileNet BPM 5.0: Java API Programming © Copyright IBM Corp. 2011
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
V5.4
Student Notebook

Uempty
Retrieve work baskets
Sample code to retrieve work baskets from a queue

VWQueue
VWQueue queue
queue ==
myPESession.getQueue(queueName);
myPESession.getQueue(queueName);
VWWorkBasket
VWWorkBasket workBaskets[]
workBaskets[] ==
queue.fetchWorkBaskets();
queue.fetchWorkBaskets();
String
String workBasketName;
workBasketName;
if(workBaskets
if(workBaskets != != null){
null){
for(int
for(int ii == 0;
0; i<workBaskets.length;
i<workBaskets.length; i++){
i++){
workBasketName
workBasketName ==
workBaskets[i].getName();
workBaskets[i].getName();
System.out.println("Workbasket
System.out.println("Workbasket name:"
name:" ++
workBasketName);
workBasketName);
}}
}}

© Copyright IBM Corporation 2011

Figure 9-49. Sample code to retrieve work baskets from a queue F1561.0

Notes:
The sample code in this page assumes that a VWSession is already established and
assigned to a variable called myPESession.

© Copyright IBM Corp. 2011 Unit 9. Use Roles and Workbaskets 9-59
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
Student Notebook

Retrieve work baskets

Steps to retrieve the work basket columns

1. Retrieve the Process Engine session.

2. Retrieve the work basket (from VWRole or VWQueue).

3. Retrieve the work basket columns.

vwWorkBasket.getColumns()
vwWorkBasket.getColumns()

4. Retrieve the work basket column information.

column.getName(…)
column.getName(…)
column.getAuthoredName()
column.getAuthoredName()
column.getPrompt(…)
column.getPrompt(…)
column.getType()
column.getType()

© Copyright IBM Corporation 2011

Figure 9-50. Steps to retrieve the work basket columns F1561.0

Notes:

9-60 IBM FileNet BPM 5.0: Java API Programming © Copyright IBM Corp. 2011
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
V5.4
Student Notebook

Uempty
Retrieve work baskets
vwWorkbasket.getColumns()

public
public VWWorkBasket.Column[]
VWWorkBasket.Column[] getColumns()
getColumns()

• Parameters
–Nothing
• Returns
–An array of the work basket columns

© Copyright IBM Corporation 2011

Figure 9-51. vwWorkbasket.getColumns() F1561.0

Notes:
Get the columns defined for the in-basket.
Example use: Get the columns and use the information to creating the list heading for the
in-basket user interface.
Columns are used to decide which workflow fields are displayed.
In-basket columns are the workflow fields that are configured to be displayed on the
in-basket browse list.

© Copyright IBM Corp. 2011 Unit 9. Use Roles and Workbaskets 9-61
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
Student Notebook

Retrieve work baskets

vwColumn.getName()

public
public String
String getName()
getName()

• Parameters
–Nothing
• Returns
–The name of the work basket column

© Copyright IBM Corporation 2011

Figure 9-52. vwColumn.getName() F1561.0

Notes:

9-62 IBM FileNet BPM 5.0: Java API Programming © Copyright IBM Corp. 2011
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
V5.4
Student Notebook

Uempty
Retrieve work baskets
vwColumn.getPrompt()

public
public String
String getPrompt()
getPrompt()

• Parameters
–Nothing
• Returns
–A String containing the text currently assigned as the entry prompt
for the column

© Copyright IBM Corporation 2011

Figure 9-53. vwColumn.getPrompt() F1561.0

Notes:
The prompt is the Colum Label defined in Process Configuration Console.

© Copyright IBM Corp. 2011 Unit 9. Use Roles and Workbaskets 9-63
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
Student Notebook

Retrieve work baskets

Sample code to get work basket columns
VWWorkBasket.Column
VWWorkBasket.Column columns[]
columns[] ==
workbasket.getColumns();
workbasket.getColumns();
if(columns
if(columns !=!= null)
null) {{
for(int
for(int ii == 0;
0; ii << columns.length;
columns.length; i++){
i++){
String
String name
name == columns[i].getName();
columns[i].getName();
String
String authoredName
authoredName ==
columns[i].getAuthoredName();
columns[i].getAuthoredName();
String
String prompt
prompt == columns[i].getPrompt();
columns[i].getPrompt();
int
int type
type == columns[i].getType();
columns[i].getType();
String
String typeString
typeString ==
VWFieldType.getLocalizedString(type);
VWFieldType.getLocalizedString(type);
boolean
boolean isSortable
isSortable == columns[i].isSortable();
columns[i].isSortable();
System.out.println(…);
System.out.println(…);
}}

© Copyright IBM Corporation 2011

Figure 9-54. Sample code to get work basket columns F1561.0

Notes:
The sample code in this page assumes that the VWWorkBasket type variable called work
basket has already been assigned a valid value.

9-64 IBM FileNet BPM 5.0: Java API Programming © Copyright IBM Corp. 2011
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
V5.4
Student Notebook

Uempty
Retrieve work baskets
VWWorkBasket.Filter object
• Filters the work items based on your query specification
defined in Process Engine.
• Custom filters that filter the work items at run time

© Copyright IBM Corporation 2011

Figure 9-55. VWWorkBasket.Filter object F1561.0

Notes:
In-basket filters – These configurable options are selected by the user to further limit the
in-basket list.

© Copyright IBM Corp. 2011 Unit 9. Use Roles and Workbaskets 9-65
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
Student Notebook

Retrieve work baskets

vwWorkBasket.getFilters()

public
public VWWorkBasket.Filter[]
VWWorkBasket.Filter[] getFilters()
getFilters()

• Returns
–An array of the work basket filter
• Notes:
–This method gets the filters defined for the in-basket.
–Filters the work items based on your defined query specification.
–Example use: Get the list of fields that can be used to further filter
the in-basket.

© Copyright IBM Corporation 2011

Figure 9-56. vwWorkBasket.getFilters() F1561.0

Notes:

9-66 IBM FileNet BPM 5.0: Java API Programming © Copyright IBM Corp. 2011
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
V5.4
Student Notebook

Uempty
Retrieve work baskets
vwFilter.getName()

public
public String
String getName()
getName()

• Parameters
–Nothing
• Returns
–The name of the work basket filter

© Copyright IBM Corporation 2011

Figure 9-57. vwFilter.getName() F1561.0

Notes:

© Copyright IBM Corp. 2011 Unit 9. Use Roles and Workbaskets 9-67
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
Student Notebook

Retrieve work baskets

vwFilter.getOperator()

public
public int
int getOperator()
getOperator()

• Parameters
–Nothing
• Returns
–The search field operator used for filtering

© Copyright IBM Corporation 2011

Figure 9-58. vwFilter.getOperator() F1561.0

Notes:

9-68 IBM FileNet BPM 5.0: Java API Programming © Copyright IBM Corp. 2011
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
V5.4
Student Notebook

Uempty
Retrieve work baskets
Sample code to get work basket filters

VWWorkBasket.Filter
VWWorkBasket.Filter filters[]
filters[] ==
workbasket.getFilters();
workbasket.getFilters();
if(filters
if(filters != null) {{
!= null)
for(int
for(int ii == 0;
0; ii << filters.length;
filters.length; i++)
i++) {{
String
String filterName
filterName == filters[i].getName();
filters[i].getName();
String
String authoredFilterName ==
authoredFilterName
filters[i].getAuthoredName();
filters[i].getAuthoredName();
String
String description
description ==
filters[i].getDescription();
filters[i].getDescription();
String
String prompt == filters[i].getPrompt();
prompt filters[i].getPrompt();
int type = filters[i].getType();
int type = filters[i].getType();
int
int operator
operator == filters[i].getOperator();
filters[i].getOperator();
System.out.println
System.out.println (…); (…);
}}
}}

© Copyright IBM Corporation 2011

Figure 9-59. Sample code to get work basket filters F1561.0

Notes:
The sample code in this page assumes that the VWWorkBasket type variable called work
basket has already been assigned a valid value.

© Copyright IBM Corp. 2011 Unit 9. Use Roles and Workbaskets 9-69
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
Student Notebook

Retrieve work baskets

Demonstrations
• Retrieve work baskets for a given role.
• Retrieve work baskets from a queue.
• Retrieve work basket information.
• Retrieve work basket columns.
• Retrieve work basket filters.
–Explore the code sample.
–Run the solution code.
–Observe the results.

© Copyright IBM Corporation 2011

Figure 9-60. Demonstrations F1561.0

Notes:
Demonstration notes - 1
Retrieve work baskets for a given role
1. Start Eclipse and open the BPMJavaAPISolution project.
2. Review the code for retrieving work baskets for a given role in the
getWorkBasketsEDU(…) method of the InbasketsEDU.java file.
3. The getWorkBasketsEDU(…) method is called inside the getRolesforUserEDU(…)
method.
4. Run the code and verify the results as instructed in the “Use Roles and Work Baskets”
unit in the Student Exercises.
Demonstration notes - 2
Retrieve work baskets from a queue
1. Review the code for retrieving work baskets from a queue in the
getQueueWorkbasketsEDU(…) method of the InbasketsEDU.java file.

9-70 IBM FileNet BPM 5.0: Java API Programming © Copyright IBM Corp. 2011
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
V5.4
Student Notebook

Uempty 2. The getQueueWorkbasketsEDU(…) method is called inside the main(…) method.

3. Run the code and verify the results as instructed in the “Use Roles and Work Baskets”
unit in the Student Exercises.
Demonstration notes - 3
Retrieve work basket information
Review the code for retrieving work basket information in the getWorkBasketInfoEDU(…)
method of the InbasketsEDU.java file.
1. The getWorkBasketInfoEDU(…) method is called inside the
getQueueWorkbasketsEDU(…) method.
2. Run the code and verify the results as instructed in the “Use Roles and Work Baskets”
unit in the Student Exercises.
Demonstration notes - 4
Retrieve work basket columns
1. Review the code for retrieving work baskets columns in the
getWorkbasketColumnsEDU(…) method of the InbasketsEDU.java file.
2. The getWorkbasketColumnsEDU(…) method is called inside the
getWorkBasketInfoEDU(…) method.
3. Run the code and verify the results as instructed in the “Use Roles and Work Baskets”
unit in the Student Exercises.
Demonstration notes - 5
Retrieve work basket filters
1. Review the code for converting work basket filter operator constant to String in the
getFilterOperatorEDU(…) method of the InbasketsEDU.java file.
2. The getFilterOperatorEDU(…) method is called inside the
getWorkbasketFiltersEDU(…) method.
3. Review the code for retrieving work basket filters in the getWorkbasketFiltersEDU(…)
method of the InbasketsEDU.java file.
4. The getWorkbasketFiltersEDU(…) method is called inside the
getWorkBasketInfoEDU(…) method.
5. Run the code and verify the results as instructed in the “Use Roles and Work Baskets”
unit in the Student Exercises.

© Copyright IBM Corp. 2011 Unit 9. Use Roles and Workbaskets 9-71
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
Student Notebook

Retrieve work baskets

Activities
In your Student Exercises
• Unit: Use Roles and Work Baskets
• Lesson: Retrieve work baskets
• Activities:
–Retrieve work baskets for a given role.
–Retrieve work baskets from a queue.
–Retrieve work basket information.

© Copyright IBM Corporation 2011

Figure 9-61. Activities F1561.0

Notes:
Use your Student Exercises to perform the activities listed.

9-72 IBM FileNet BPM 5.0: Java API Programming © Copyright IBM Corp. 2011
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
V5.4
Student Notebook

Uempty Lesson 9.4. Query work items from work baskets

© Copyright IBM Corp. 2011 Unit 9. Use Roles and Workbaskets 9-73
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
Student Notebook

Lesson:
Query work items from work baskets
• Why is this lesson important to you?
– The accounting department needs to process work items in the
work basket. As the programmer, you are going to write code to
retrieve the work items from the work baskets.

© Copyright IBM Corporation 2011

Figure 9-62. Lesson: Query work items from work baskets F1561.0

Notes:

9-74 IBM FileNet BPM 5.0: Java API Programming © Copyright IBM Corp. 2011
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
V5.4
Student Notebook

Uempty
Query work items from work baskets
Activities that you need to complete

• Retrieve work items from work baskets.

© Copyright IBM Corporation 2011

Figure 9-63. Activities that you need to complete F1561.0

Notes:
These are the activities that you are going to perform in this lesson.

© Copyright IBM Corp. 2011 Unit 9. Use Roles and Workbaskets 9-75
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
Student Notebook

Query work items from work baskets

Performing an in-basket query

• List the items from the

“Mortgage Review” in-
basket.
• User customizes the in-
basket query.
• Retrieve the items from the
in-basket based on the
customization.
ƒ The database query goals:
– Select {columns}* from Queue1
where <predefined query
criteria> AND <in-basket filters>
order by <a display column>
ƒ Query is consistent and predictable.
ƒ Database administrator can
evaluate query plan and create the
necessary indices.

65
© Copyright IBM Corporation 2011

Figure 9-64. Performing an in-basket query F1561.0

Notes:
Example in-basket query:
Select Name, PhoneNum, LoanAmt, CreditScore from
MortgageQueue where LoanAmt >= 50000.00 and ZipCode = Var1 order by
CreditScore
Display columns: “Name, PhoneNum, LoanAmt, CreditScore”
Predefined query criteria: “LoanAmt >= 500000.00”
In-basket filter criteria: “ZipCode = Var1”

9-76 IBM FileNet BPM 5.0: Java API Programming © Copyright IBM Corp. 2011
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
V5.4
Student Notebook

Uempty
Query work items from work baskets
Example of an in-basket query

• Example query:
– Select Name, PhoneNum, LoanAmt, CreditScore from
MortgageQueue where LoanAmt >= 500000.00 and ZipCode
= Var1 order by CreditScore.
• Display columns: “Name, PhoneNum, LoanAmt,
CreditScore”
• Predefined query criteria: “LoanAmt >= 500000.00”
• In-basket filter criteria: “ZipCode = Var1”

© Copyright IBM Corporation 2011

Figure 9-65. Example of an in-basket query F1561.0

Notes:

© Copyright IBM Corp. 2011 Unit 9. Use Roles and Workbaskets 9-77
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
Student Notebook

Query work items from work baskets

Putting it all together – The database query
• The database query:
–Select {columns}* from Queue1 where <predefined query
criteria> AND <in-basket filters> order by <a display
column>.
• Query is consistent and predictable.
• Database administrator can evaluate query plan and create the
necessary indices.

© Copyright IBM Corporation 2011

Figure 9-66. Putting it all together - The database query F1561.0

Notes:

9-78 IBM FileNet BPM 5.0: Java API Programming © Copyright IBM Corp. 2011
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
V5.4
Student Notebook

Uempty
Query work items from work baskets
vwQueue.fetchWorkBasket(…)

public
public VWWorkBasket
VWWorkBasket fetchWorkBasket(String
fetchWorkBasket(String
workBasketName)
workBasketName)

• Parameters
–workBasketName – Specify a String value for the work basket name.
• Returns
– An VWWorkBasket object that is specified

© Copyright IBM Corporation 2011

Figure 9-67. vwQueue.fetchWorkBasket(...) F1561.0

Notes:

© Copyright IBM Corp. 2011 Unit 9. Use Roles and Workbaskets 9-79
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
Student Notebook

Query work items from work baskets

vwWorkBasket.fetchNextBatch(…)

public
public VWWorkBasket.QueryResults
VWWorkBasket.QueryResults fetchNextBatch
fetchNextBatch
(queryFlags,
(queryFlags, bufferSize,
bufferSize, sortColumn,
sortColumn, filterNames,
filterNames,
substitutionVariables,
substitutionVariables, lasWorkRecStr, fetchType)
lasWorkRecStr, fetchType)

• Parameters
–queryFlags – Specify an integer value for the query options.
–See the notes for the other parameters.
• Returns
– A QueryResults object containing the results of the query.
– If the end of the query results was reached in the preceding call to
this method, null is returned.
• Notes
–This method fetches the next batch of query results.

© Copyright IBM Corporation 2011

Figure 9-68. vwWorkBasket.fetchNextBatch(...) F1561.0

Notes:
Parameters
Queryflags - Use the vertical bar (|) and plus (+) operators to combine the flags. See the
QUERY_* properties on VWQuery for descriptions of the possible query flags.
buffer_size - An integer value indicating the maximum number of elements to return. The
default value for bufferSize is 50.
sort_column - A String containing the name of the column to sort by.
filter_names - A String array of the names of the filters to use for the query.
substition_vars – An array of objects containing the values to substitute for the
placeholder variables specified in the SQL WHERE clauses for the filters.
lastWorkRecStr - A base64-encoded String containing the last record of the query results.
If this value is null, the query starts from the beginning.
fetchType - An integer value associated with the element type to be retrieved using the
object returned by VWRosterQuery.

9-80 IBM FileNet BPM 5.0: Java API Programming © Copyright IBM Corp. 2011
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
V5.4
Student Notebook

Uempty
Query work items from work baskets
vwWorkBasket.QueryResults.getWorkObjects()

public
public java.lang.Object[]
java.lang.Object[] getWorkObjects()
getWorkObjects()

• Parameters
–None
• Returns
– An Object array of work objects
• Notes
–This method gets the array of work objects that is returned by the
query.

© Copyright IBM Corporation 2011

Figure 9-69. vwWorkBasket.QueryResults.getWorkObjects() F1561.0

Notes:

© Copyright IBM Corp. 2011 Unit 9. Use Roles and Workbaskets 9-81
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
Student Notebook

Query work items from work baskets

vwWorkBasket.QueryResults.getLastRecord()

public
public String
String getLastRecord()
getLastRecord()

• Parameters
–None
• Returns
– A String containing the last record of the query results
• Notes
–VWWorkBasket.QueryResults represents the query result as
returned by the fetchNextBatch method.

© Copyright IBM Corporation 2011

Figure 9-70. vwWorkBasket.QueryResults.getLastRecord() F1561.0

Notes:
Use the fetchNextBatch() method and the lastRecord object from the returned
QueryResult object to query the next and following pages of the query results.

9-82 IBM FileNet BPM 5.0: Java API Programming © Copyright IBM Corp. 2011
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
V5.4
Student Notebook

Uempty
Query work items from work baskets
Sample code for work basket query

VWWorkBasket
VWWorkBasket workbasket
workbasket ==
queue.fetchWorkBasket(workbasketName);
queue.fetchWorkBasket(workbasketName);
int
int pageSize == 4;
pageSize 4;
……
//
// Query
Query the
the first
first page
page
int queryFlags = VWQueue.QUERY_NO_OPTIONS;
int queryFlags = VWQueue.QUERY_NO_OPTIONS;
int
int fetchType
fetchType ==
VWFetchType.FETCH_TYPE_QUEUE_ELEMENT;
VWFetchType.FETCH_TYPE_QUEUE_ELEMENT;
VWWorkBasket.QueryResults
VWWorkBasket.QueryResults queryResults
queryResults ==
workbasket.fetchNextBatch(queryFlags,pageSize,
workbasket.fetchNextBatch(queryFlags,pageSize,
null,filterNames,subsVars,null,fetchType);
null,filterNames,subsVars,null,fetchType);

© Copyright IBM Corporation 2011

Figure 9-71. Sample code for work basket query F1561.0

Notes:

© Copyright IBM Corp. 2011 Unit 9. Use Roles and Workbaskets 9-83
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
Student Notebook

Query work items from work baskets

Sample code to display queue elements

VWQueueElement
VWQueueElement queueElements[]
queueElements[] == null;
null;
int pageNumber =
int pageNumber = 1; 1;
String
String lastRecord
lastRecord == queryResults.getLastRecord();
queryResults.getLastRecord();
queueElements = (VWQueueElement[])
queueElements = (VWQueueElement[])
queryResults.getWorkObjects();
queryResults.getWorkObjects();
System.out.println("Process
System.out.println("Process page: page: "" ++ pageNumber
pageNumber ++
"Count:"
"Count:" ++ queueElements.length);
queueElements.length);
for
for (int
(int ii == 0;
0; ii << queueElements.length;
queueElements.length; i++)i++) {{
VWQueueElement
VWQueueElement qe qe == queueElements[i];
queueElements[i];
String workObjNo = qe.getWorkObjectNumber();
String workObjNo = qe.getWorkObjectNumber();
String
String queueName
queueName == qe.getQueueName();
qe.getQueueName();
String stepName = qe.getStepName();
String stepName = qe.getStepName();
System.out.println("Wob
System.out.println("Wob number:"+workObjNo
number:"+workObjNo ++
"Queue
"Queue name:"+queueName+"Step
name:"+queueName+"Step Name:"+stepName);
Name:"+stepName);

© Copyright IBM Corporation 2011

Figure 9-72. Sample code to display queue elements F1561.0

Notes:

9-84 IBM FileNet BPM 5.0: Java API Programming © Copyright IBM Corp. 2011
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
V5.4
Student Notebook

Uempty
Query work items from work baskets
Sample code to display column name and value

……
VWWorkBasket.Column
VWWorkBasket.Column columns[]
columns[] ==
workbasket.getColumns();
workbasket.getColumns();
if
if (columns
(columns !=!= null){
null){
for
for (int
(int jj == 0;
0; jj << columns.length;
columns.length; j++){
j++){
String
String name
name == columns[j].getAuthoredName();
columns[j].getAuthoredName();
System.out.println("column
System.out.println("column name:"name:" ++ name);
name);
Object
Object value
value == qe.getDataField(name).getValue();
qe.getDataField(name).getValue();
String
String valueString
valueString == value.toString();
value.toString();
System.out.println("Value:"
System.out.println("Value:" ++ valueString);
valueString);
}}
}}

© Copyright IBM Corporation 2011

Figure 9-73. Sample code to display column name and value F1561.0

Notes:

© Copyright IBM Corp. 2011 Unit 9. Use Roles and Workbaskets 9-85
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
Student Notebook

Query work items from work baskets

Demonstrations
• Retrieve work items from work baskets.
–Explore the code sample.
–Run the solution code.
–Observe the results.

© Copyright IBM Corporation 2011

Figure 9-74. Demonstrations F1561.0

Notes:
DEMONSTRATION —
1. Start Eclipse and open the BPMJavaAPISolution project.
2. Review the code for retrieving the details of the work items in the getWorkItemsEDU(…)
method of the InbasketsEDU.java file.
3. Notice that some of the variables (passed as parameters to this method) are initialized
in the main() method, before calling this method.
4. Run the code and verify the results as instructed in the “Use Roles and Work Baskets”
unit in the Student Exercises.

9-86 IBM FileNet BPM 5.0: Java API Programming © Copyright IBM Corp. 2011
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
V5.4
Student Notebook

Uempty
Query work items from work baskets
Activities
In your Student Exercises
• Unit: Use Roles and Work Baskets
• Lesson: Query work items from work baskets
• Activities:
– Retrieve work items from work baskets.

© Copyright IBM Corporation 2011

Figure 9-75. Activities F1561.0

Notes:
Use your Student Exercises to perform the activities listed.

© Copyright IBM Corp. 2011 Unit 9. Use Roles and Workbaskets 9-87
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
Student Notebook

9-88 IBM FileNet BPM 5.0: Java API Programming © Copyright IBM Corp. 2011
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
V5.4
Student Notebook

Uempty Unit 10. Configure Email Notification

What this unit is about

This unit describes how to configure the Process Engine for email
notification and test email notification by launching a workflow. This
unit also describes how to customize email notification templates.

What you should be able to do

After completing this unit, you should be able to:
• Configure the Process Engine for email notification
• Launch a Workflow a workflow and test email notification
• Customize email notification templates.

How you will check your progress

• Successfully complete the activities in the Student Exercises book.

References
www.ibm.com/support/documentation/us/en (Support & downloads
page)
Note: IBM FileNet products belong to the Information Management
product set.

© Copyright IBM Corp. 2011 Unit 10. Configure Email Notification 10-1
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
Student Notebook

Configure email notification

Unit lessons
This unit contains the following lessons:
• Configure email notification
• Customize email notification templates

© Copyright IBM Corporation 2011

Figure 10-1. Unit lessons F1561.0

Notes:
Lessons in this unit
This unit has two lessons. The second lesson relies on information and skills taught in the
prior lesson. For best results, do these lessons in the sequence presented.
Configure email notification – In this lesson, you configure email notification using
Process Configuration Console, Workplace, and Process Task Manager. You also launch a
workflow and test email notification.
Customize email notification templates – In this lesson, you customize email notification
templates.

10-2 IBM FileNet BPM 5.0: Java API Programming © Copyright IBM Corp. 2011
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
V5.4
Student Notebook

Uempty Lesson 10.1. Configure email notification

© Copyright IBM Corp. 2011 Unit 10. Configure Email Notification 10-3
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
Student Notebook

Lesson:
Configure email notification
• Why is this lesson important to you?
–You want to configure workflows so that they automatically send
email notification for these events:
• Workflow participants about work assignments
• Workflow participants when work associated with a step or workflow is
overdue
• A designated tracker when a workflow exception occurs
–Participants receive a reminder of the pending deadline.

© Copyright IBM Corporation 2011

Figure 10-2. Lesson: Configure email notification F1561.0

Notes:

10-4 IBM FileNet BPM 5.0: Java API Programming © Copyright IBM Corp. 2011
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
V5.4
Student Notebook

Uempty
Configure email notification
Activities that you need to complete

• Configure the Process Engine for email notification

• Launch a workflow and test email notification

© Copyright IBM Corporation 2011

Figure 10-3. Activities that you need to complete F1561.0

Notes:
These are the activities that you are going to perform in this lesson.

© Copyright IBM Corp. 2011 Unit 10. Configure Email Notification 10-5
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
Student Notebook

Configure email notification

Email notifications
• Process Engine provides a framework for email notifications.
• Email notifications
–Used to notify or remind workflow participants about work
assignments and dead lines
• IBM FileNet provides default email notification files
–Text files (.msg), containing HTML-formatted content
–Available for customizing

© Copyright IBM Corporation 2011

Figure 10-4. Email notifications F1561.0

Notes:

10-6 IBM FileNet BPM 5.0: Java API Programming © Copyright IBM Corp. 2011
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
V5.4
Student Notebook

Uempty
Configure email notification
Steps to configure email notification

1. Configure Process Configuration Console.

– Configure Event Logging options.
– Enable Notification on VWService.
2. Configure user preferences in the Workplace.
– Enter the email address that the server uses to notify you.
– Turn on or off selected email notifications.
3. Configure Process Task Manager notification.
– Specify the information for the Process Engine for sending emails
• Mail server
• Port number
• User information
4. Set deadline and reminder notification emails in workflows.

© Copyright IBM Corporation 2011

Figure 10-5. Steps to configure email notification F1561.0

Notes:
Help paths
• IBM FileNet P8 Version 5.0 Information Center > Administering IBM FileNet P8 >
Administering Process Engine > Workflow administration tasks > Coordinate workflow
design > Enable email notification
• IBM FileNet P8 Version 5.0 Information Center > Administering IBM FileNet P8 >
Working with Process Task Manager > Process Engine > Configure Process Engine >
Email notification

© Copyright IBM Corp. 2011 Unit 10. Configure Email Notification 10-7
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
Student Notebook

Configure email notification

Configure event logging options
• Enable email notification.
• Expose the system fields and data fields in the event log:
–Process Engine notification emails get the data from the event logs.
• Set event logging options in Isolated Region Properties
–Logging
options enabled for
• Exception
• Begin operation

© Copyright IBM Corporation 2011

Figure 10-6. Configure event logging options F1561.0

Notes:
The screen capture shows the Event logging settings in the Isolated Region Properties
window of the Process Configuration Console.
Event logging settings determine whether the Process Engine generates a log message
when certain system-level events occur within the selected isolated region. Each event
logging option represents an event category. If you enable logging for a category, the
occurrence of any event within that category generates a log message.
You need to enable logging for the Exception and Begin Operation categories for email
notification to work.
Configure these logging options using the Configuration Console.
Expose the associated system fields, if they have not already been exposed, or are not
exposed by default. Exposed fields are system and data fields in a roster, queue, or event
log that have been made available for searches and sorting.

10-8 IBM FileNet BPM 5.0: Java API Programming © Copyright IBM Corp. 2011
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
V5.4
Student Notebook

Uempty
Configure email notification
Enable notification on VWService
• Process Configuration Console > VWService Properties >
Runtime Options tab
–Select the Enable notification option.

© Copyright IBM Corporation 2011

Figure 10-7. Enable notification on VWService F1561.0

Notes:
The screen capture shows the VWService Properties window and the configuration for
Runtime Options.

© Copyright IBM Corp. 2011 Unit 10. Configure Email Notification 10-9
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
Student Notebook

Configure email notification

Configure user preferences

© Copyright IBM Corporation 2011

Figure 10-8. Configure user preferences F1561.0

Notes:
The screen capture shows the User Preferences page in Workplace XT and maps to how it
appears in the email.
Task Settings
General specifies email settings. Enter the email address that the server uses to notify you
of new or updated task activities.
Step Notification specifies whether to notify you of steps in a workflow.
• New assignment determines if you receive an email notice when a step is assigned to
you. The default is off.
• Expired step deadline determines if you receive an email notice when a step deadline
has been passed without completing the step. The default is off.
• Reminders determines if you receive an email notice that a step deadline is
approaching. The default is off.

10-10 IBM FileNet BPM 5.0: Java API Programming © Copyright IBM Corp. 2011
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
V5.4
Student Notebook

Uempty Originator Notification specifies whether the workflow originator is notified when a
milestone is reached.
Tracker Notification specifies whether to notify you about events for the workflows that
you are assigned to track.
• New tracker assignment specifies whether to notify you when a new workflow is
launched for which you are a designated tracker.
• Workflow deadline reminders specifies whether to notify you about workflow deadline
reminders for which you are a designated tracker.
• Workflow deadline expired specifies whether to notify you about expired workflow
deadlines for which you are a designated tracker.
• Workflow exception specifies whether to notify you when a workflow exception occurs
for which you are a designated tracker.
• Expired step deadline specifies whether to notify you about expired step deadlines for
which you are a designated tracker.
• Milestone reached specifies whether to notify you when a milestone is reached for a
workflow for which you are a designated tracker.

© Copyright IBM Corp. 2011 Unit 10. Configure Email Notification 10-11
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
Student Notebook

Configure email notification

Configure Process Task Manager

Mail Server

© Copyright IBM Corporation 2011

Figure 10-9. Configure Process Task Manager F1561.0

Notes:
The screen capture shows the Process Task Manager settings for the Notification.
SMTP Host The complete host name for an SMTP server on the network running the
SMTP Service on the port specified by the SMTP Port parameter. The SMTP server can be
a Process Engine or another server on your network. See the Help for Process
Development for general information on setting up an SMTP server.
SMTP Port The port on which the SMTP Service is running. The default value is 25.
Character Set The character set to be used in encoding the email message. The default is
ISO-8859-1. If you change this value, you must set the Encode From Field parameter.
Email Logon ID The name used for the account that you want the Process Engine to use
to log on to the mail server application. You must use ASCII characters only. Example:
[email protected]
Email Logon Password The password associated with the Email Logon ID.
Email From ID The name that you want to appear in the From field on the notification
emails. You can use extended ASCII characters.

10-12 IBM FileNet BPM 5.0: Java API Programming © Copyright IBM Corp. 2011
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
V5.4
Student Notebook

Uempty Encode From Field Indicates whether to encode the contents of the Email from ID field.
Select On if the Email From ID field contains extended ASCII characters. Off is the default.

© Copyright IBM Corp. 2011 Unit 10. Configure Email Notification 10-13
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
Student Notebook

Configure email notification

Deadlines and reminders (1)
• Can be specified for
–The entire workflow
–Specific steps in the workflow
• When a deadline or reminder expires, the item is displayed
with the appropriate symbol
Reminder Overdue

• If enabled and configured, an email message is sent to the

specified users based on the reminder or deadline expiration

• Deadline and reminder calculations: F_Overdue

Deadline time is added to queue time. system field
states
0 = default
1 = reminder
2 = expired
3 = completed
Reminder time is subtracted from deadline time.
© Copyright IBM Corporation 2011

Figure 10-10. Deadlines and reminders (1) F1561.0

Notes:
The screen capture shows the Reminder icon and Overdue icons and how deadline and
reminder are calculated.
The workflow author can specify deadlines and reminders for an entire workflow and for
one or more specific steps in a workflow.
A deadline is an optional, time-based scheduling constraint that requires a step or workflow
to be completed within a certain amount of time. For a step, the deadline is relative to the
time that the step was routed to the participant. For a workflow, the deadline is relative to
the time that the workflow was launched. A value of 0 indicates the absence of a deadline.
A reminder is notification of a pending deadline for completing a step. When specifying a
reminder, indicate the amount of time prior to the expiration of the deadline that the
reminder needs to be sent. A value of 0 indicates the absence of a reminder.
When the deadline or reminder expires, the item Status in the user’s Inbox and Tracker
queue is updated to indicate the event that occurred.

10-14 IBM FileNet BPM 5.0: Java API Programming © Copyright IBM Corp. 2011
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
V5.4
Student Notebook

Uempty Depending on the participant’s selection in User Preferences, an email notification is sent
to the workflow participant and tracker for the workflow when deadlines or reminders
expire. If the user has not enabled that notification option, then no email message is sent.
The F_Overdue system field tracks the state of the work item with respect to deadlines and
reminders with an integer value.
0 = default (no reminder or deadline)
1 = reminder
2 = expired
3 = workflow completed

© Copyright IBM Corp. 2011 Unit 10. Configure Email Notification 10-15
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
Student Notebook

Configure email notification

Deadlines and reminders (2)
• Set deadline and reminder to the complete workflow in
Process Designer workflow properties.
–Deadline status is displayed in Administrator and Tracker.
–Email notification is sent on event, if configured.
Workflow search

© Copyright IBM Corporation 2011

Figure 10-11. Deadlines and reminders (2) F1561.0

Notes:
Screen capture shows workflow search in the Process Administrator and Process Tracker.
Specify time limits for reminders and deadlines in the workflow properties window in
Process Designer.
A deadline measures time relative to the time that the workflow was launched.
A reminder about the pending deadline is sent at the specified time (prior to the workflow
deadline) in the email.
If the workflow is not completed before the deadline, a tracker with this feature enabled is
notified that the workflow is overdue by means of an email and the Inbox queue.

10-16 IBM FileNet BPM 5.0: Java API Programming © Copyright IBM Corp. 2011
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
V5.4
Student Notebook

Uempty
Configure email notification
Error opening Step Processor using email
• Email messages are not deleted when the work item is
completed.
• A completed work item that is opened using the email
message might give the following error:

© Copyright IBM Corporation 2011

Figure 10-12. Error opening Step Processor using email F1561.0

Notes:
The screen capture shows an error message that occurs when an email link for a Step
Processor is accessed.
When users complete a work item, either through email notification or Workplace, the work
item is moved to the next step of the workflow. The notification email, however, is not
deleted. If the user clicks the link in the notification email to open the step processor, an
error might occur because the step element no longer exists for this step.
Users need to manually delete notification emails when the work items are completed.

© Copyright IBM Corp. 2011 Unit 10. Configure Email Notification 10-17
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
Student Notebook

Configure email notification

Demonstrations
• Configure logging options in Process Configuration Console.
• Configure user preferences in Workplace.
• Configure Process Task Manager.
• Configure a workflow for email notification.
• Launch a workflow and test email notification.

© Copyright IBM Corporation 2011

Figure 10-13. Demonstrations F1561.0

Notes:
DEMONSTRATION —
Use the instructions in the “Configure email notification” lesson of the “Configure Email
Notification” unit in the Student Exercises for details of each demonstration.
This activity requires a third-party mail server and a mail client, which are installed on the
student system.

10-18 IBM FileNet BPM 5.0: Java API Programming © Copyright IBM Corp. 2011
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
V5.4
Student Notebook

Uempty
Configure email notification
Activities
In your Student Exercises
• Unit: Configure Email Notification
• Lesson: Configure email notification
• Activities:
–Configure the Process Engine for email notification
–Launch a workflow and test email notification

© Copyright IBM Corporation 2011

Figure 10-14. Activities F1561.0

Notes:
Use your Student Exercises to perform the activities listed.

© Copyright IBM Corp. 2011 Unit 10. Configure Email Notification 10-19
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
Student Notebook

10-20 IBM FileNet BPM 5.0: Java API Programming © Copyright IBM Corp. 2011
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
V5.4
Student Notebook

Uempty Lesson 10.2. Customize email notification templates

© Copyright IBM Corp. 2011 Unit 10. Configure Email Notification 10-21
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
Student Notebook

Lesson:
Customize email notification templates
• Why is this lesson important to you?
– In your email notifications, you want to
• Add your company logo
• Add information about the work item data fields

© Copyright IBM Corporation 2011

Figure 10-15. Lesson: Customize email notification templates F1561.0

Notes:

10-22 IBM FileNet BPM 5.0: Java API Programming © Copyright IBM Corp. 2011
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
V5.4
Student Notebook

Uempty
Customize email notification templates
Activities that you need to complete

• Customize email notification templates.

© Copyright IBM Corporation 2011

Figure 10-16. Activities that you need to complete F1561.0

Notes:
These are the activities that you are going to perform in this lesson.

© Copyright IBM Corp. 2011 Unit 10. Configure Email Notification 10-23
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
Student Notebook

Customize email notification templates

Default email notification templates
• The message templates are used to create the notification
emails.
–They are text files (.msg), containing HTML-formatted content.
–They can be customized by modifying the code in the files from the
working directory.
• Templates contain placeholder variables embedded in HTML.
–Process Engine services provides the values for the variables at run
time.
• When Process Engine notification process is invoked, the
process does the following:
–Locates the appropriate template based on the event.
–Retrieves the data from the notification information database.
–Populates the variables with the field values.
–Dispatches the file using the SMTP service.
© Copyright IBM Corporation 2011

Figure 10-17. Default email notification templates F1561.0

Notes:
The email notification files contain placeholder variables embedded in the HTML.
The values for these variables are supplied by the Process Engine services at run time,
where a given field variable obtains its values from the field that is named by the string
following the "$" prefix in the field variable name.
The Process Engine notification process caches the notification files when the process
starts. When the process is invoked, the email notification service on the workflow server
locates the appropriate template based on the event, retrieves the necessary data from the
notification information database, populates the variables with the relevant field
information, and dispatches the file using the SMTP service (specified using the Process
Engine Task Manager).

10-24 IBM FileNet BPM 5.0: Java API Programming © Copyright IBM Corp. 2011
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
V5.4
Student Notebook

Uempty
Customize email notification templates
Location of email notification templates
• Files located on Process Engine server Linux host
– /opt/IBM/FileNet/ProcessEngine/msg/1 (IBM FileNet Workplace)
– /opt/IBM/FileNet/ProcessEngine/msg/2 (IBM FileNet Web services)
– /opt/IBM/FileNet/ProcessEngine/msg/3 (IBM FileNet Open Client)
– /opt/IBM/FileNet/ProcessEngine/msg/4 (IBM FileNet Collaboration)
– /opt/IBM/FileNet/ProcessEngine/msg/5 (IBM FileNet Web Content
Manager)
– /opt/IBM/FileNet/ProcessEngine/msg/6 (IBM FileNet Records Manager)
– /opt/IBM/FileNet/ProcessEngine/msg/7 (IBM FileNet Workplace XT)
– /opt/IBM/FileNet/ProcessEngine/msg/8 (IBM ECM Widgets for Lotus
Mashups )
– /opt/IBM/FileNet/ProcessEngine/msg/9 (IBM ECM Widgets for Business
Space)
– /opt/IBM/FileNet/ProcessEngine/msg/100 (Custom Application)

© Copyright IBM Corporation 2011

Figure 10-18. Location of email notification templates F1561.0

Notes:

© Copyright IBM Corp. 2011 Unit 10. Configure Email Notification 10-25
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
Student Notebook

Customize email notification templates

Email template files
• 10 message files correspond to the 10 notification options
–Overdue Step Notification stp_deadline.msg
–Step Assignment Notification stp_new.msg
–Step Reminder Notification stp_reminder.msg
–Tracking Assignment Notification trk_new.msg
–Overdue Tracker Step Notification trk_stp_deadline.msg
–Workflow Exception Notification trk_exception.msg
–Workflow Overdue Notification trk_wf_deadline.msg
–Workflow Reminder Notification trk_wf_reminder.msg
–Workflow Milestone Notification org_milestone.msg
–Workflow Tracker Milestone Notification trk_milestone.msg
© Copyright IBM Corporation 2011

Figure 10-19. Email template files F1561.0

Notes:
File name and Description
stp_deadline.msg - Sent to a workflow participant to indicate that a step is overdue for
completion.
stp_new.msg - Sent as a notification that the participant was assigned a new step.
stp_reminder.msg - Sent as a reminder to a workflow participant that a step deadline is
approaching.
trk_new.msg - Sent to a participant to indicate that he or she has been designated as a
tracker for this workflow.
trk_stp_deadline.msg - Sent to a tracker to indicate that a workflow step has not been
completed and is overdue.
trk_exception.msg - Sent as a notification to a workflow tracker that a workflow exception
occurred.

10-26 IBM FileNet BPM 5.0: Java API Programming © Copyright IBM Corp. 2011
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
V5.4
Student Notebook

Uempty trk_wf_deadline.msg - Sent to an assigned tracker to indicate that a workflow is overdue for
completion.
trk_wf_reminder.msg - Sent to an assigned tracker as a notification that a workflow
deadline is approaching.
org_milestone.msg - Sent to the workflow originator, which typically is the person who
launched the workflow, as a notification that a workflow milestone was reached.
trk_milestone.msg - Sent to an assigned tracker as a notification that workflow milestone
was reached.

© Copyright IBM Corp. 2011 Unit 10. Configure Email Notification 10-27
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
Student Notebook

Customize email notification templates

Email notification types
• Step Notifications
–Step Assignment
–Step Reminder
–Expired Step Deadline
• Tracker Notifications
–New Assignment
–Expired Step Deadline
• Workflow Notifications
–Workflow Exception
–Workflow Reminder
–Expired Workflow Deadline
• Milestone Notifications
–Milestone reached for originator
–Milestone reached for tracker
© Copyright IBM Corporation 2011

Figure 10-20. Email notification types F1561.0

Notes:

10-28 IBM FileNet BPM 5.0: Java API Programming © Copyright IBM Corp. 2011
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
V5.4
Student Notebook

Uempty
Customize email notification templates
Steps to customize templates
1. Save the original files before modifying them.
2. Change the file attribute from Read-only to Read/Write.
3. Modify the message content delivered to users.
– Edit the .msg file (in HTML format) with a text editor.
– Include exposed data fields or system fields in messages.
4. Update the templates in the Process Task Manager.
Note:
• The number and function of messages is fixed.
– New events cannot be added.
– The .msg files for existing mail events cannot be removed.

© Copyright IBM Corporation 2011

Figure 10-21. Steps to customize templates F1561.0

Notes:
Because the notification files contain HTML formatted content, the Process Engine system
administrator can modify the content of the files to match corporate identity or other needs.
Although the message content can be edited, the number and function of messages are
fixed. New events cannot be added, and .msg files corresponding to existing mail events
cannot be removed without generating server errors.

© Copyright IBM Corp. 2011 Unit 10. Configure Email Notification 10-29
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
Student Notebook

Customize email notification templates

Update the custom templates
• In Process Task Manager, select
–<Server Name> > Process Engine > Language Packs > English
(United States)
• Select the check box “Update email notification templates”
• Enter the location of templates for the Template Directory.
• Apply changes.
• Restart the Process Service.

© Copyright IBM Corporation 2011

Figure 10-22. Update the custom templates F1561.0

Notes:

10-30 IBM FileNet BPM 5.0: Java API Programming © Copyright IBM Corp. 2011
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
V5.4
Student Notebook

Uempty
Customize email notification templates
Email notification template contents
• Sample excerpt from stp_new.msg file

Exposed fields in Event Log

URL to WebServer in vwserver.ini

© Copyright IBM Corporation 2011

Figure 10-23. Email notification template contents F1561.0

Notes:
The illustration shows the content of stp_new.msg file.
The email notification files contain placeholder variables embedded in the HTML. The
values for these variables are supplied by the Process Engine services at run time, where a
given field variable obtains its values from the field that is named by the string following the
"$" prefix in the field variable name. The Process Engine notification process caches the
notification files when the process starts.
When the email message is assembled, the vwnotify process polls the event log assigned
by the workflow work class and uses predefined fields, delimited by <$..>, which serve as
placeholders for calculated values or values assigned in a region event log and dispatches
the file using the SMTP service (specified using the Process Engine Task Manager).
Message Predefined Fields
F_BOUNDUSERID[1] F_ORIGINATOR[1]
F_CREATETIMEF_STARTTIME
F_EMAILADDRF_STEPINSTR

© Copyright IBM Corp. 2011 Unit 10. Configure Email Notification 10-31
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
Student Notebook

F_ENQUEUETIME F_STEPLABEL
F_MILESTONE_NAME F_WORKSPACEID
Note: Not all predefined F_xxx system fields can be used in a message, because the work
object and the log event record might not have the information expected for the message.

10-32 IBM FileNet BPM 5.0: Java API Programming © Copyright IBM Corp. 2011
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
V5.4
Student Notebook

Uempty
Customize email notification templates
Optional email notification variables
• $F_SUBJPREFIX
• $F_WEBSERVER
• $F_WORKQUEUE
• $F_WORKFLOW_DEADLINE
• $F_MILESTONE_NAME
• $F_STEPLABEL
• $F_STEPINSTR
• An exposed, user-defined
field variable
–Follows the "$" prefix in the
field variable name
–Example: $customer_name

© Copyright IBM Corporation 2011

Figure 10-24. Optional email notification variables F1561.0

Notes:
By default, all of the system fields that are necessary to supply required variable
information are exposed in the event log. If an optional field is not exposed in the event log,
that optional variable is ignored.
$F_STEPPROC - String specifying the name of the processor that the participant must use
to complete the step.
$F_WEBSERVER - String containing the name of the Application Engine server that a
participant must attach to in order to respond to the notice. The name is also used to supply
the background and notification type images
$F_WORKFLOW_DEADLINE - String containing a computed value. The value represents
the result of the following computation: F_StartTime + F_WFDeadline(*60). (The
F_WFDeadline field contains the workflow deadline value, in minutes.)
$F_SUBJPREFIX - String containing the prefix for the subject line of the message.
$F_MILESTONE_NAME - String containing the name of the milestone defined in Process
Designer, which was reached.

© Copyright IBM Corp. 2011 Unit 10. Configure Email Notification 10-33
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
Student Notebook

Customize email notification templates

Custom new step notification

Server
Configuration

Link to Step Processor using Web Server

© Copyright IBM Corporation 2011

Figure 10-25. Custom new step notification F1561.0

Notes:
The screen captures show a custom notification for a New Step Assignment. An image
field and a custom data field retrieved from the exposed data fields in the event log are
configured in the stp_new.msg file and are displayed in the email notification.
The email header also gets information configured in the Process Task Manager
Notification option.

10-34 IBM FileNet BPM 5.0: Java API Programming © Copyright IBM Corp. 2011
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
V5.4
Student Notebook

Uempty
Customize email notification templates
Demonstrations
• Customize email notification templates.

© Copyright IBM Corporation 2011

Figure 10-26. Demonstrations F1561.0

Notes:
DEMONSTRATION —
Use the instructions in the “Customize email notification templates” lesson of the
“Configure Email Notification” unit in the Student Exercises for details.

© Copyright IBM Corp. 2011 Unit 10. Configure Email Notification 10-35
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
Student Notebook

Customize email notification templates

Activities
In your Student Exercises
• Unit: Configure Email notification
• Lesson: Customize email notification templates
• Activities:
– Customize email notification templates.

© Copyright IBM Corporation 2011

Figure 10-27. Activities F1561.0

Notes:
Use your Student Exercises to perform the activities listed.

10-36 IBM FileNet BPM 5.0: Java API Programming © Copyright IBM Corp. 2011
Course materials may not be reproduced in whole or in part
without the prior written permission of IBM.
V5.4.0.3

backpg
Back page